# Organizations

> Read organizations and their membership with a person's credentials.

An Organization owns Workspaces and API keys. Administration requests use a signed-in person's
session or Bearer access token. An API key cannot administer its organization. The active
organization comes from that authenticated context; request bodies cannot choose another tenant.

See [the Organization object](https://augenta.pages.dev/docs/api-reference/organization-object.md) for its available operations, all attributes and an example object.

## Endpoints

| Endpoint                                                                                          | Purpose                                                            |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [`GET /v1/orgs`](https://augenta.pages.dev/docs/api-reference/list-organizations.md)                     | List organizations the person can access.                          |
| [`GET /v1/orgs/{id}`](https://augenta.pages.dev/docs/api-reference/get-organization.md)                  | Retrieve the active organization, optionally including membership. |
| [`GET /v1/orgs/{id}/members`](https://augenta.pages.dev/docs/api-reference/list-organization-members.md) | Page through its organization roster.                              |

There is no direct Organization create, rename or delete resource operation. Organization names
and organization membership are managed through the identity provider. The console's
`PUT /v1/me/active-org` operation switches session context; its result is an acknowledgment or a
browser authorization redirect, rather than an Organization resource.

## Organization fields

| Field         | Meaning                                                                      |
| ------------- | ---------------------------------------------------------------------------- |
| `object`      | Always `organization`.                                                       |
| `id`          | Augenta Organization ID. Use it in resource routes.                          |
| `name`        | Organization display name.                                                   |
| `role`        | The signed-in person's organization role, when loaded.                       |
| `memberCount` | Full roster count, or `null` when it has not been read.                      |
| `workosOrgId` | Optional external identity-provider reference; it is not the resource ID.    |
| `members`     | Initial membership list page, present when requested with `include=members`. |

Organization list pages also contain `activeOrgId` and `personalOrgPolicy: "visible"`.
Personal organizations remain available after someone joins a team, so their data stays reachable.
Lists use live keyset pagination and recheck access on every page; they are not frozen membership
snapshots. Follow `nextPageUrl` unchanged. See [Pagination](https://augenta.pages.dev/docs/pagination.md).

## Retrieve an organization

```bash
curl --fail-with-body -sS --get "https://api.augenta.ai/v1/orgs/$AUGENTA_ORG_ID" \
  -H "Authorization: Bearer $AUGENTA_ACCESS_TOKEN" \
  --data-urlencode "include=members"
```

```json
{
  "object": "organization",
  "id": "aug-example",
  "name": "Example",
  "role": "owner",
  "memberCount": 1,
  "members": {
    "object": "list",
    "url": "/v1/orgs/aug-example/members",
    "data": [{
      "object": "organization_member",
      "id": "user-example",
      "userId": "user-example",
      "organization": "aug-example",
      "name": "Example User",
      "role": "owner",
      "hasSignedIn": true
    }],
    "nextPageUrl": null
  }
}
```

A membership's `id` is its `userId` within the parent organization. A provisioned person may
appear with `hasSignedIn: false`. The roster uses the identity provider when available, with
local membership as its fallback. Neither an empty page nor a local fallback proves a person
was deleted from the external directory.
