# Organizations (Beta)

List and manage organizations the authenticated caller can access.

## List organizations the caller can access

> Returns every organization the authenticated user / API key can act in, ordered with the primary (default-fallback) org first. Use this to discover valid \`org\_id\` values to pass into other beta tools — required for users who belong to multiple orgs and want to scope a particular call to a non-primary org.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationMembership"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Organizations (Beta)"],"summary":"List organizations the caller can access","description":"Returns every organization the authenticated user / API key can act in, ordered with the primary (default-fallback) org first. Use this to discover valid `org_id` values to pass into other beta tools — required for users who belong to multiple orgs and want to scope a particular call to a non-primary org."}}},"components":{"schemas":{"OrganizationMembership":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID. Pass as `org_id` to other tools."},"name":{"type":"string","description":"Human-readable organization name."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'), or null if unset. For other org-management fields (postal address, deactivation flag, created_at), use `get_organization` on a specific `org_id`.","nullable":true},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"description":"Caller's role in this org: 'user', 'admin', 'support', 'cloud_rep', or 'restricted_user'. Staff users are reported as 'admin' for every active org."},"kind":{"description":"How the caller has access: 'direct' (regular member), 'staff' (staff-level access to every active org), or 'partnership' (inherited via a channel partnership).","enum":["direct","staff","partnership"]},"is_primary":{"type":"boolean","description":"True for the org the caller's tokens default to when no `org_id` is passed. Matches the earliest-joined direct membership returned by `User.active_memberships`."},"denied_permissions":{"type":"array","description":"List of `Resource:action` strings the caller's role is denied (e.g. 'PurchasePlanV2:execute'). Anything not listed is permitted. Use to gate write/destructive recommendations.","items":{"type":"string"}}},"required":["denied_permissions","id","is_primary","kind","name","role"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get an organization's management details

> Returns the org-management view of a single organization: name, domain, primary address, deactivation flag, and created\_at. For the cross-org list of orgs the caller can access (with role / kind / denied\_permissions), use \`GET /organizations\`.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations/{org_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Organizations (Beta)"],"summary":"Get an organization's management details","description":"Returns the org-management view of a single organization: name, domain, primary address, deactivation flag, and created_at. For the cross-org list of orgs the caller can access (with role / kind / denied_permissions), use `GET /organizations`."}}},"components":{"schemas":{"OrganizationDetail":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"description":"Organization ID."},"name":{"type":"string","description":"Organization name. Unique across the platform."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'). Used for domain-based onboarding flows.","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true,"description":"When the org was created."},"primary_address":{"description":"The org's primary postal address (optional).","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"required":["name"],"additionalProperties":false},"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Address identifier."},"line1":{"type":"string","description":"Street address, line 1."},"line2":{"type":"string","default":null,"description":"Street address, line 2 (optional).","nullable":true},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State / region / province."},"zip":{"type":"string","description":"Postal / ZIP code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')."}},"required":["city","country","line1","state","zip"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Update an organization's management details

> Partial-update: every field is optional. Send only the fields you want to change. Sending \`primary\_address\` replaces the existing address in full; pass null to clear it. Deactivation is intentionally not exposed here — use \`POST /organizations/\<org\_id>/deactivate\`. Requires the caller to have admin role on the org (the \`Organization:write\` casbin permission).

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations/{org_id}":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganization"}}}},"tags":["Organizations (Beta)"],"summary":"Update an organization's management details","description":"Partial-update: every field is optional. Send only the fields you want to change. Sending `primary_address` replaces the existing address in full; pass null to clear it. Deactivation is intentionally not exposed here — use `POST /organizations/<org_id>/deactivate`. Requires the caller to have admin role on the org (the `Organization:write` casbin permission)."}}},"components":{"schemas":{"OrganizationDetail":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"description":"Organization ID."},"name":{"type":"string","description":"Organization name. Unique across the platform."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'). Used for domain-based onboarding flows.","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true,"description":"When the org was created."},"primary_address":{"description":"The org's primary postal address (optional).","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"required":["name"],"additionalProperties":false},"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Address identifier."},"line1":{"type":"string","description":"Street address, line 1."},"line2":{"type":"string","default":null,"description":"Street address, line 2 (optional).","nullable":true},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State / region / province."},"zip":{"type":"string","description":"Postal / ZIP code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')."}},"required":["city","country","line1","state","zip"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"UpdateOrganization":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"New organization name."},"domain":{"type":"string","minLength":1,"description":"New email domain, or null to clear.","nullable":true},"primary_address":{"description":"Replacement primary address. Send the full address object. Pass null to clear the existing address.","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Deactivate an organization

> Soft-disables the organization: it stops appearing in \`list\_organizations\` results and members lose access. Intentionally a one-way door from this API surface — there is no corresponding reactivate endpoint, and once deactivated the org cannot be reached via these admin endpoints at all (the auth layer filters deactivated orgs). Reactivation requires reaching out to Archera support. Returns 204 with no body — there is no further state the caller can read post-deactivation. Requires the caller to have admin role on the org (the \`Organization:write\` casbin permission).

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations/{org_id}/deactivate":{"post":{"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Organizations (Beta)"],"summary":"Deactivate an organization","description":"Soft-disables the organization: it stops appearing in `list_organizations` results and members lose access. Intentionally a one-way door from this API surface — there is no corresponding reactivate endpoint, and once deactivated the org cannot be reached via these admin endpoints at all (the auth layer filters deactivated orgs). Reactivation requires reaching out to Archera support. Returns 204 with no body — there is no further state the caller can read post-deactivation. Requires the caller to have admin role on the org (the `Organization:write` casbin permission)."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.archera.ai/api-reference/beta-api/organizations-beta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.