> Markdown version of https://authpi.com/docs/reference/core-api/organizations/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Organizations — AuthPI Core API

Organization management endpoints. Organizations are groups of users within an Issuer, commonly used for multi-tenancy where each customer is an Organization.

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/organizations

**List Organizations**

Lists all organizations within an issuer.

Organizations are groups of users, commonly used for multi-tenancy where each customer or team is an organization.

**Use cases for organizations:**
- **Multi-tenant SaaS** - Each customer is an organization with their own users
- **Team workspaces** - Group users into teams with shared permissions
- **B2B applications** - Manage enterprise customers and their employees

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor (org_id from previous response) |
| `status` | active \| suspended \| deleted | Optional | Filter by organization status. If not specified, returns all non-deleted organizations. |
| `sso_enabled` | true \| false | Optional | Filter by SSO enabled status. |
| `sso_only` | true \| false | Optional | Filter by SSO-only enforcement (password login disabled). |
| `mfa_required` | true \| false | Optional | Filter by MFA requirement. |
| `invitation_enabled` | true \| false | Optional | Filter by invitation enabled status. |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Paginated list of organizations | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/organizations

**Create Organization**

Creates a new organization within an issuer.

Organizations are containers for grouping users, typically representing:
- Customer accounts in a multi-tenant application
- Teams or departments within a company
- Projects or workspaces

**After creating an organization:**
1. Add members using the Add Organization Member endpoint
2. Configure roles and permissions as needed
3. Optionally set up API keys for service-to-service authentication

**Custom metadata:**
Use the `metadata` field to store application-specific data like billing tier, feature flags, or external system IDs.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Optional | A name for the resource. |
| `description` | string \| null | Optional | A description for the resource. Markdown supported. |
| `logo_url` | string | Optional | A URL |
| `org_type` | business \| nonprofit \| government | Optional |  |
| `max_members` | integer | Optional |  |
| `default_member_scopes` | string[] | Optional |  |
| `invitation_enabled` | boolean | Optional |  |
| `invitation_message` | string | Optional |  |
| `address` | Address | Optional |  |
| `business_details` | object | Optional |  |
| `contact` | object | Optional |  |
| `social_links` | object[] | Optional |  |
| `scopes` | string[] | Optional |  |
| `security` | object | Optional |  |
| `custom_fields` | object | Optional |  |
| `metadata` | object | Optional |  |
| `created_by_user_id` | string | Optional | User ID |
| `creator_scopes` | string[] | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Organization created successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}

**Get Organization**

Retrieves the full details of an organization by its ID.

Returns complete organization information including:
- **Profile** - Name, display name, description, logo
- **Settings** - Custom configuration and metadata
- **Statistics** - Member count and other aggregates
- **Timestamps** - Creation and last update times

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Organization retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}

**Update Organization**

Updates an organization's details.

All fields in the request body are optional - only include the fields you want to change.

**Updatable fields:**
- **name** - Internal identifier (must be unique within the issuer)
- **display_name** - User-facing name shown in UIs
- **description** - Optional description
- **logo_url** - URL to the organization's logo
- **metadata** - Custom key-value data (merged with existing metadata)

**Metadata updates:**
Metadata is merged, not replaced. To remove a key, set it to `null`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | Optional | A name for the resource. |
| `description` | string \| null | Optional | A description for the resource. Markdown supported. |
| `logo_url` | string \| null | Optional |  |
| `status` | active \| suspended | Optional |  |
| `status_reason` | string | Optional |  |
| `status_by` | string | Optional |  |
| `max_members` | integer | Optional |  |
| `default_member_scopes` | string[] | Optional |  |
| `invitation_enabled` | boolean | Optional |  |
| `invitation_message` | string \| null | Optional |  |
| `address` | Address \| null | Optional |  |
| `business_details` | object | Optional |  |
| `contact` | object \| null | Optional |  |
| `social_links` | object[] | Optional |  |
| `scopes` | string[] | Optional |  |
| `security` | object | Optional |  |
| `sso` | object | Optional |  |
| `custom_fields` | object | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Organization updated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## DELETE /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}

**Delete Organization**

Deletes an organization and removes all its members.

**What happens on deletion:**
- All organization API keys are revoked before anything else is removed — if revocation fails, the deletion is aborted and can be retried
- All member associations are removed
- Organization metadata is deleted
- Users are NOT deleted (they remain in the issuer)

**Before deleting:**
1. Consider exporting organization data if needed for compliance
2. Notify affected users if appropriate

**Note:** This is a permanent operation. Unlike users and issuers, organizations do not have a soft-delete grace period.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/members

**List Organization Members**

Lists all members of an organization with their roles and status.

Each membership includes:
- **User reference** - The user ID and basic profile info
- **Role** - The member's role within the organization (e.g., owner, admin, member)
- **Scopes** - Fine-grained permissions granted to this member
- **Status** - Active, suspended, or removed

Use the `status` filter to find suspended members or audit removed memberships.

Use the `scope` filter to find all members who have a specific effective scope (including scopes inherited from groups).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor from previous response |
| `status` | active \| suspended | Optional | Filter by membership status |
| `scope` | string | Optional | Filter members by effective scope (includes scopes inherited from groups) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Members retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/members

**Add Organization Member**

Adds a user as a member of an organization.

The user must already exist in the issuer. This endpoint creates the membership association with the specified role and permissions.

**Roles:**
Define roles that make sense for your application. Common patterns:
- `owner` - Full control, can delete the organization
- `admin` - Can manage members and settings
- `member` - Standard access

**Scopes:**
Use scopes for fine-grained permissions within your application. Scopes are included in access tokens when the user authenticates in the context of this organization.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `member_id` | string | Required |  |
| `scopes` | string[] | Optional |  |
| `groups` | string[] | Optional |  |
| `user_title` | string | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Member added successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 409 | **Conflict** - The request conflicts with the current state of the resource. | `ApiError` |

## PATCH /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/members/{member_id}

**Update Organization Member**

Updates a member's role, scopes, or status within an organization.

**Common operations:**
- **Change role** - Promote or demote a member (e.g., member → admin)
- **Update scopes** - Add or remove fine-grained permissions
- **Suspend member** - Temporarily block access without removing membership

**Status changes:**
- Setting status to `suspended` immediately blocks the member from accessing organization resources
- Setting status back to `active` restores access
- To permanently remove, use the Remove Organization Member endpoint instead

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `member_id` | string | Required | The unique identifier of the organization member (user or agent) |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | active \| suspended | Optional |  |
| `scopes` | string[] | Optional |  |
| `groups` | string[] | Optional |  |
| `user_title` | string \| null | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Member updated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## DELETE /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/members/{member_id}

**Remove Organization Member**

Removes a member from an organization.

This permanently removes the membership. The member:
- Immediately loses access to organization resources
- Will no longer see the organization in their memberships
- Retains their account in the issuer (if a user)

**Alternative:** To temporarily block access while retaining membership history, use Update Organization Member to set status to `suspended` instead.

**Note:** Removing the last owner of an organization may leave it without administrative access. Consider transferring ownership first.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `member_id` | string | Required | The unique identifier of the organization member (user or agent) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/groups

**List Organization Groups**

Lists all groups defined in an organization.

Groups are named bundles of scopes that can be assigned to members. When a member is assigned a group, they inherit all of the group's scopes.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor from previous response |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Groups retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/groups

**Create Organization Group**

Creates a new group in an organization.

A group is a named bundle of scopes. Assign groups to members instead of managing individual scopes. When a group's scopes change, all members with that group automatically inherit the updated scopes.

Organizations can have up to 100 groups.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | A name for the resource. |
| `description` | string \| null | Optional | A description for the resource. Markdown supported. |
| `scopes` | string[] | Required |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Group created successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/groups/{group_id}

**Get Organization Group**

Retrieves a single group by ID.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `group_id` | string | Required | The unique identifier of the group |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Group retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/groups/{group_id}

**Update Organization Group**

Updates a group's name, description, or scopes.

When a group's scopes are updated, all memberships referencing this group will have their effective scopes re-computed and synced. This means scope changes propagate automatically to all members of the group.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `group_id` | string | Required | The unique identifier of the group |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Optional | A name for the resource. |
| `description` | string \| null | Optional | A description for the resource. Markdown supported. |
| `scopes` | string[] | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Group updated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## DELETE /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/groups/{group_id}

**Delete Organization Group**

Deletes a group from the organization.

Memberships that reference this group will have their effective scopes re-computed without the deleted group's scopes. The group ID remains in membership records but is silently ignored during scope resolution.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `group_id` | string | Required | The unique identifier of the group |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/sso/rotate-secret

**Rotate SSO Client Secret**

Rotates the OIDC client secret used for SSO authentication.

A new secret is generated and stored on the organization's SSO configuration. The new secret is returned in the response—**store it securely, as it cannot be retrieved again**.

**Prerequisites:**
- SSO must be enabled and configured with OIDC on the organization
- Update your identity provider with the new secret promptly

**Note:** Unlike client secret rotation, there is no grace period—the old secret is replaced immediately.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | SSO secret rotated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/sso/domains

**Add SSO Domain**

Adds a domain to the organization's SSO configuration for email-based IdP routing.

After adding a domain, you must verify ownership by creating a DNS TXT record with the provided values. Use the **Verify SSO Domain** endpoint to complete verification.

**How it works:**
1. Add the domain using this endpoint
2. Create the DNS TXT record as instructed in the response
3. Call the verify endpoint once the DNS record has propagated
4. Once verified, users with email addresses on this domain will be routed to the organization's SSO provider

**Prerequisites:**
- SSO must be enabled on the organization

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | Required |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Domain added successfully. Create the DNS TXT record to verify ownership. | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 409 | **Conflict** - The request conflicts with the current state of the resource. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/sso/domains/{domain}/verify

**Verify SSO Domain**

Verifies ownership of an SSO domain by checking the DNS TXT record.

After adding a domain and creating the required DNS TXT record, call this endpoint to verify ownership. DNS propagation may take up to 48 hours, though it typically completes within minutes.

**Response:**
- `verified: true` — Domain ownership confirmed, SSO routing is active for this domain
- `verified: false` with `error` — Verification failed, check the error message for details

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `domain` | string | Required | Domain name (e.g., 'auth.example.com') |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Verification result | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## DELETE /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/sso/domains/{domain}

**Remove SSO Domain**

Removes a domain from the organization's SSO configuration.

Once removed, users with email addresses on this domain will no longer be routed to the organization's SSO provider. This action is immediate and permanent.

**Note:** You can remove both verified and unverified domains.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `domain` | string | Required | Domain name (e.g., 'auth.example.com') |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/invitations

**List Invitations**

Lists invitations for an organization with optional status filtering.

Invitations allow you to invite users to join an organization before they have an account. When a user accepts an invitation, they become a member with the scopes defined in the invitation.

**Invitation statuses:**

- **pending** - Waiting for the invitee to accept or decline
- **accepted** - Invitee accepted and is now a member
- **declined** - Invitee explicitly declined the invitation
- **expired** - Invitation expired before being accepted
- **revoked** - Admin revoked the invitation

Use the `status` filter to find pending invitations that need follow-up or to audit historical invitations.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor from previous response |
| `status` | pending \| accepted \| declined \| expired \| revoked | Optional | Filter by invitation status |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Invitations retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/invitations

**Create Invitation**

Creates a new invitation to join an organization.

An invitation email will be sent to the specified email address with a link to accept the invitation. The invitee does not need to have an existing account—they can create one when accepting.

**Invitation lifecycle:**

1. Admin creates invitation with email and scopes
2. System sends invitation email with secure link
3. Invitee clicks link and creates account (or logs in if existing)
4. Invitee accepts invitation and becomes organization member

**Scopes:**

Define what permissions the invitee will have in the organization. Common patterns:
- `["member"]` - Basic read access
- `["member", "write"]` - Read and write access
- `["admin"]` - Full administrative access

**Expiration:**

By default, invitations expire after 7 days. You can customize this with `expires_in_seconds` (max 30 days).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email_invited` | string | Required |  |
| `scopes` | string[] | Required |  |
| `user_title` | string | Optional |  |
| `message` | string | Optional |  |
| `inviter` | Inviter | Optional |  |
| `expires_in_seconds` | integer | Optional |  |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Invitation created successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 409 | **Conflict** - The request conflicts with the current state of the resource. | `ApiError` |

## GET /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/invitations/{invitation_id}

**Get Invitation**

Retrieves a specific invitation by ID.

Returns the full invitation details including:

- **Invitee email** - The email address the invitation was sent to
- **Status** - Current state of the invitation
- **Scopes** - Permissions the invitee will receive upon acceptance
- **Timestamps** - When created, expires, and accepted/declined/revoked

**Note:** The invitation challenge is never returned in API responses for security reasons.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `invitation_id` | string | Required | The unique identifier of the invitation |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Invitation retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/invitations/{invitation_id}

**Update Invitation**

Updates a pending invitation.

Only pending invitations can be updated. Once an invitation is accepted, declined, expired, or revoked, it cannot be modified.

**Updatable fields:**

- **scopes** - Change the permissions the invitee will receive
- **user_title** - Update the job title/role description
- **message** - Modify the custom invitation message
- **expires_at** - Extend or shorten the expiration (must be in the future)

**Common operations:**

- **Extend expiration**: Set `expires_at` to a future timestamp
- **Change scopes before acceptance**: Update `scopes` array
- **Add context**: Update `message` with additional information

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `invitation_id` | string | Required | The unique identifier of the invitation |

### Request body

Content type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `scopes` | string[] | Optional |  |
| `user_title` | string \| null | Optional |  |
| `message` | string \| null | Optional |  |
| `expires_at` | integer | Optional | Unix timestamp in milliseconds |
| `metadata` | Metadata | Optional |  |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Invitation updated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/invitations/{invitation_id}/revoke

**Revoke Invitation**

Revokes a pending invitation.

Once revoked, the invitation link will no longer work and the invitee cannot accept it. This action is permanent.

**Use cases:**

- Cancel an invitation sent to the wrong email
- Remove access before it's granted
- Clean up invitations that are no longer needed

**Note:** Only pending invitations can be revoked. Invitations that have already been accepted, declined, or expired cannot be revoked.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `invitation_id` | string | Required | The unique identifier of the invitation |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## POST /v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/invitations/{invitation_id}/resend

**Resend Invitation**

Resends the invitation email to the invitee.

Use this when the original invitation email was not received or the invitee needs a reminder.

**Requirements:**

- Invitation must be in `pending` status
- Invitation must not be expired

**Note:** The invitation link and challenge remain the same—only the email is resent. Consider updating the expiration date if it's close to expiring.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `issuer_id` | string | Required | The unique identifier of the issuer |
| `org_id` | string | Required | The unique identifier of the organization |
| `invitation_id` | string | Required | The unique identifier of the invitation |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |