> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/guides/api-reference/organizations.md).

# Organizations

Manage organizations, users, roles, invitations, and preferences.

## GET /api/v1/organizations/{organization\_id}

> Get Organization

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Organization":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the organization.\nFormat: organizations/{organization_id}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the organization."},"logo_data_uri":{"type":"string","title":"The organization logo as a data URI following RFC 2397.\nFormat: data:[<mediatype>][;encoding],<data>\nExample: data:image/png;encoding,<encoded-image-data>"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the organization was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the organization was last updated.","readOnly":true},"owner_display_name":{"type":"string","description":"The display name of the organization owner.","readOnly":true},"owner_email":{"type":"string","description":"The email address of the organization owner.","readOnly":true}},"description":"An Organization is the top-level resource container.","required":["title"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}":{"get":{"summary":"Get Organization","operationId":"GetOrganization","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Organization"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Organizations"]}}}}
```

## GET /api/v1/me/organizations

> Current User Organizations

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CurrentUserOrganizationsResponse":{"type":"object","properties":{"user_organizations":{"type":"array","items":{"$ref":"#/components/schemas/v1Organization"},"description":"The list of organizations the current user is a member of."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`CurrentUserOrganizations` to get the next page of results. If this field is\nempty, it means there are no more results."}},"description":"Response message for listing organizations for the current user."},"v1Organization":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the organization.\nFormat: organizations/{organization_id}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the organization."},"logo_data_uri":{"type":"string","title":"The organization logo as a data URI following RFC 2397.\nFormat: data:[<mediatype>][;encoding],<data>\nExample: data:image/png;encoding,<encoded-image-data>"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the organization was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the organization was last updated.","readOnly":true},"owner_display_name":{"type":"string","description":"The display name of the organization owner.","readOnly":true},"owner_email":{"type":"string","description":"The email address of the organization owner.","readOnly":true}},"description":"An Organization is the top-level resource container.","required":["title"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/me/organizations":{"get":{"summary":"Current User Organizations","operationId":"CurrentUserOrganizations","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CurrentUserOrganizationsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"page_size","description":"The maximum number of organizations to return.\nIf unspecified, at most 50 organizations will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"A page token, received from a previous `ListCurrentUserOrganizations` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListCurrentUserOrganizations` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter string following AIP-160 filtering standards.\nExample: \"title='My Organization'\"","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Optional comma-separated list of fields to order by, following AIP-132.\nSupported fields: title, create_time, update_time\nExample: \"title\", \"create_time desc\", \"update_time desc,title\"\nDefault ordering is by title ascending (alphabetical) if not specified.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Organizations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/preferences

> Get Organization Preferences

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1OrganizationPreferences":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the organization preferences.\nFormat: `organizations/{organization}/preferences`"},"support_team_access":{"type":"boolean","description":"Support team access to workspaces in the organization for debugging issues."},"general":{"$ref":"#/components/schemas/v1GeneralPreferences"}},"description":"Represents organization-specific settings or preferences."},"v1GeneralPreferences":{"type":"object","properties":{"time_zone":{"type":"string","description":"The time zone preference.\nShould be an IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\", \"UTC\")."},"time_format":{"$ref":"#/components/schemas/v1TimeFormat"},"date_format":{"$ref":"#/components/schemas/v1DateFormat"},"decimal_symbol":{"$ref":"#/components/schemas/v1DecimalSymbol"},"decimal_places":{"type":"integer","format":"int32","description":"The number of digits after decimal point. Valid range [0, 10].\n\nMarked `optional` so that 0 (a legitimate user choice meaning\n\"integer display\") can be distinguished from \"field not set\". Wire\nformat is identical to a plain `int32` in proto3 — old clients that\nomit the field still decode as absent on the server."},"measurement_system":{"$ref":"#/components/schemas/v1MeasurementSystem"},"week_start":{"$ref":"#/components/schemas/v1WeekStart"},"language_code":{"type":"string","description":"The user-facing language as a BCP-47 locale code (e.g. `en`, `es`, `zh-Hans`).\nEmpty string indicates inherit-from-parent-scope or system default."}},"description":"General preferences for display and formatting.\nUsed by both workspace and organization preferences, and embedded in\nUserPreferences to allow user-level overrides for every field."},"v1TimeFormat":{"type":"string","enum":["TIME_FORMAT_UNSPECIFIED","TIME_FORMAT_12_HOUR","TIME_FORMAT_24_HOUR"],"default":"TIME_FORMAT_UNSPECIFIED","description":"Supported time formats.\n\n - TIME_FORMAT_UNSPECIFIED: Unspecified time format.\n - TIME_FORMAT_12_HOUR: 12-hour format (1:00 PM).\n - TIME_FORMAT_24_HOUR: 24-hour format (13:00)."},"v1DateFormat":{"type":"string","enum":["DATE_FORMAT_UNSPECIFIED","DATE_FORMAT_DD_MM_YYYY_SLASH","DATE_FORMAT_MM_DD_YYYY_SLASH","DATE_FORMAT_YYYY_MM_DD_DASH","DATE_FORMAT_DD_MM_YYYY_DASH","DATE_FORMAT_MM_DD_YYYY_DASH","DATE_FORMAT_YYYY_MM_DD_SLASH","DATE_FORMAT_DD_MM_YYYY_DOT","DATE_FORMAT_MM_DD_YYYY_DOT","DATE_FORMAT_YYYY_MM_DD_DOT","DATE_FORMAT_DD_MMM_YYYY","DATE_FORMAT_MMM_DD_YYYY","DATE_FORMAT_DD_MMMM_YYYY","DATE_FORMAT_MMMM_DD_YYYY"],"default":"DATE_FORMAT_UNSPECIFIED","description":"Supported date formats.\n\n - DATE_FORMAT_UNSPECIFIED: Unspecified date format.\n - DATE_FORMAT_DD_MM_YYYY_SLASH: DD/MM/YYYY format.\n - DATE_FORMAT_MM_DD_YYYY_SLASH: MM/DD/YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_DASH: YYYY-MM-DD format (ISO 8601).\n - DATE_FORMAT_DD_MM_YYYY_DASH: DD-MM-YYYY format.\n - DATE_FORMAT_MM_DD_YYYY_DASH: MM-DD-YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_SLASH: YYYY/MM/DD format.\n - DATE_FORMAT_DD_MM_YYYY_DOT: DD.MM.YYYY format (European style).\n - DATE_FORMAT_MM_DD_YYYY_DOT: MM.DD.YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_DOT: YYYY.MM.DD format.\n - DATE_FORMAT_DD_MMM_YYYY: DD MMM YYYY format (e.g., 15 Jan 2024).\n - DATE_FORMAT_MMM_DD_YYYY: MMM DD, YYYY format (e.g., Jan 15, 2024).\n - DATE_FORMAT_DD_MMMM_YYYY: DD MMMM YYYY format (e.g., 15 January 2024).\n - DATE_FORMAT_MMMM_DD_YYYY: MMMM DD, YYYY format (e.g., January 15, 2024)."},"v1DecimalSymbol":{"type":"string","enum":["DECIMAL_SYMBOL_UNSPECIFIED","DECIMAL_SYMBOL_PERIOD","DECIMAL_SYMBOL_COMMA"],"default":"DECIMAL_SYMBOL_UNSPECIFIED","description":"Supported decimal symbols.\n\n - DECIMAL_SYMBOL_UNSPECIFIED: Unspecified decimal symbol.\n - DECIMAL_SYMBOL_PERIOD: Period (.) as decimal separator.\n - DECIMAL_SYMBOL_COMMA: Comma (,) as decimal separator."},"v1MeasurementSystem":{"type":"string","enum":["MEASUREMENT_SYSTEM_UNSPECIFIED","MEASUREMENT_SYSTEM_METRIC","MEASUREMENT_SYSTEM_IMPERIAL"],"default":"MEASUREMENT_SYSTEM_UNSPECIFIED","description":"Supported measurement systems.\n\n - MEASUREMENT_SYSTEM_UNSPECIFIED: Unspecified measurement system.\n - MEASUREMENT_SYSTEM_METRIC: Metric system.\n - MEASUREMENT_SYSTEM_IMPERIAL: Imperial system."},"v1WeekStart":{"type":"string","enum":["WEEK_START_UNSPECIFIED","WEEK_START_SUNDAY","WEEK_START_MONDAY"],"default":"WEEK_START_UNSPECIFIED","description":"- WEEK_START_UNSPECIFIED: Unspecified — caller should treat as \"use scope default\" (typically Sunday).\n - WEEK_START_SUNDAY: Week starts on Sunday.\n - WEEK_START_MONDAY: Week starts on Monday.","title":"First day of the week, surfaced via GeneralPreferences.week_start."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/preferences":{"get":{"summary":"Get Organization Preferences","operationId":"GetOrganizationPreferences","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1OrganizationPreferences"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Organizations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/invitations/{invitation\_id}

> Get Invitation

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Invitation":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the invitation.\nFormat: organizations/{organization}/invitations/{invitation}"},"organization_display_name":{"type":"string","description":"The organization display name."},"workspace_id":{"type":"string","description":"The workspace ID (not set if org-level invite)."},"workspace_display_name":{"type":"string","description":"The workspace display name (not set if org-level invite)."},"roles":{"type":"array","items":{"type":"string"},"description":"List of role resource names included in this invitation."},"is_accepted":{"type":"boolean","description":"Whether the invitation has been accepted.\n\nDeprecated in favor of `status`. Kept for N-1 compatibility;\nwhen `status` is `INVITATION_STATUS_ACCEPTED`, this is also true."},"redirect_organization_id":{"type":"string","description":"The organization ID to redirect to (set if invitation points to a different org)."},"redirect_workspace_id":{"type":"string","description":"The workspace ID to redirect to (set if invitation points to a different workspace)."},"status":{"$ref":"#/components/schemas/v1InvitationStatus"},"direction":{"$ref":"#/components/schemas/v1InvitationDirection"},"create_time":{"type":"string","format":"date-time","description":"Server-set creation timestamp from the underlying `user_invitations.created_at`\ncolumn. Output-only. Surfaced so the admin-side Invitations table can show\nan \"Invited on\" column.","readOnly":true}},"description":"An Invitation represents a pending invitation to join an organization or workspace."},"v1InvitationStatus":{"type":"string","enum":["INVITATION_STATUS_UNSPECIFIED","INVITATION_STATUS_SENT","INVITATION_STATUS_ACCEPTED","INVITATION_STATUS_REVOKED","INVITATION_STATUS_DECLINED"],"default":"INVITATION_STATUS_UNSPECIFIED","description":"Lifecycle status of an invitation, surfacing the Postgres enum on\n`user_invitations.invitation_status`.\n\n - INVITATION_STATUS_UNSPECIFIED: Unspecified — older clients that don't populate the field on the wire.\n - INVITATION_STATUS_SENT: Invitation has been created but the invitee has not yet acted on it.\n - INVITATION_STATUS_ACCEPTED: Invitee accepted; corresponding role assignments have been created.\n - INVITATION_STATUS_REVOKED: Inviter revoked the invitation before the invitee acted.\n - INVITATION_STATUS_DECLINED: Invitee declined the invitation."},"v1InvitationDirection":{"type":"string","enum":["INVITATION_DIRECTION_UNSPECIFIED","INVITATION_DIRECTION_INVITE","INVITATION_DIRECTION_REQUEST"],"default":"INVITATION_DIRECTION_UNSPECIFIED","description":"Distinguishes admin-initiated invitations from user-initiated access\nrequests. Both share the same `user_invitations` row shape and accept/revoke flow.\n\n - INVITATION_DIRECTION_UNSPECIFIED: Unspecified — treated as INVITE for backward compatibility.\n - INVITATION_DIRECTION_INVITE: Admin invites a user to join an org or workspace. (Default; pre-existing behavior.)\n - INVITATION_DIRECTION_REQUEST: User requests access to an org or workspace they can't currently reach\n(powers the No Access page's \"Request access\" button)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/invitations/{invitation_id}":{"get":{"summary":"Get Invitation","operationId":"GetInvitation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Invitation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"invitation_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Organizations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/invites

> List Organization User Invites

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListOrganizationUserInvitesResponse":{"type":"object","properties":{"invitations":{"type":"array","items":{"$ref":"#/components/schemas/v1UserInvitation"},"description":"The list of pending user invitations."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the page_token field in the subsequent call to\nListOrganizationUserInvites to get the next page of results."}},"description":"Response message for ListOrganizationUserInvites."},"v1UserInvitation":{"type":"object","properties":{"email":{"type":"string","description":"The user's email address."},"invitation_id":{"type":"string","description":"The invitation ID."},"role_template_ids":{"type":"array","items":{"type":"string"},"title":"Role template IDs assigned by this invitation."},"workspace_display_name":{"type":"string","description":"Workspace display name the invite is scoped to. Empty when the invite is\norg-level (no specific workspace)."},"create_time":{"type":"string","format":"date-time","title":"Server-set creation timestamp, mirroring `Invitation.create_time`.","readOnly":true},"workspace_id":{"type":"string","title":"ID of the workspace the invite is scoped to, so clients can link to it\ninstead of matching on the non-unique `workspace_display_name`. Unset when\nthe invite is org-level.","readOnly":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1InvitationRole"},"title":"Every role the invite grants, with its display title. Supersedes\n`role_template_ids` for display: that field lists built-in templates only,\nwhile this also covers workspace custom roles.","readOnly":true}},"description":"A UserInvitation represents a pending invitation summary returned by\n`ListOrganizationUserInvites` / `ListWorkspaceUserInvites`.\n\nPreviously this message only carried `email` and `invitation_id`; the\nadmin Invitations table in the v2.2 mocks needs role(s) and workspace too,\nso those are surfaced here directly to avoid one `GetInvitation` per row."},"v1InvitationRole":{"type":"object","properties":{"id":{"type":"string","title":"Identifies the role. For a built-in template this is the same bare id as in\n`UserInvitation.role_template_ids` (e.g. \"agora.viewer\"). For a workspace\ncustom role it is the resource name invites accept:\n  organizations/{organization}/workspaces/{workspace}/customRoles/{custom_role}"},"title":{"type":"string","description":"Human-readable title of the role. Empty if the role can no longer be\nresolved, in which case clients should fall back to formatting `id`."}},"description":"A role granted by an invitation, as listed on `UserInvitation`."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/invites":{"get":{"summary":"List Organization User Invites","operationId":"ListOrganizationUserInvites","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListOrganizationUserInvitesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of invitations to return.\nIf unspecified, at most 50 invitations will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"A page token, received from a previous ListOrganizationUserInvites call.\nProvide this to retrieve the subsequent page.","in":"query","required":false,"schema":{"type":"string"}},{"name":"direction","description":"Optional filter by direction. Defaults to `INVITE`.\nPass `REQUEST` to surface pending user-initiated access requests in the\nadmin UI as a separate tab.\n\n - INVITATION_DIRECTION_UNSPECIFIED: Unspecified — treated as INVITE for backward compatibility.\n - INVITATION_DIRECTION_INVITE: Admin invites a user to join an org or workspace. (Default; pre-existing behavior.)\n - INVITATION_DIRECTION_REQUEST: User requests access to an org or workspace they can't currently reach\n(powers the No Access page's \"Request access\" button).","in":"query","required":false,"schema":{"type":"string","enum":["INVITATION_DIRECTION_UNSPECIFIED","INVITATION_DIRECTION_INVITE","INVITATION_DIRECTION_REQUEST"],"default":"INVITATION_DIRECTION_UNSPECIFIED"}}],"tags":["Organizations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/roles

> List Organization Roles

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListOrganizationRolesResponse":{"type":"object","properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1Role"},"description":"The list of roles in the organization."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the page_token field in the subsequent call to\nListOrganizationRoles to get the next page of results."}},"description":"Response message for ListOrganizationRoles."},"v1Role":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the role.\nFormat: organizations/{organization}/roles/{role} (org-level)\nFormat: organizations/{organization}/workspaces/{workspace}/roles/{role} (workspace-level)","description":"List responses also use this message for entries that are not concrete\nrole instances, in which case `name` carries the referenced resource:\n  roleTemplates/{role_template} for system-defined templates\n  organizations/{organization}/workspaces/{workspace}/customRoles/{custom_role}\n    for workspace custom roles, which additionally set `custom`.\nThese are not declared as patterns above because AIP-123 requires every\npattern's final segment to contain this resource's own singular."},"title":{"type":"string","description":"Human-readable title of the role (e.g., \"Administrator\", \"Editor\")."},"description":{"type":"string","description":"Description of what this role grants."},"permissions":{"type":"array","items":{"type":"string"},"title":"List of permission strings this role grants.\nFormat: \"{action}:{resource_path}\" (e.g., \"GET:/api/v1/me\")","readOnly":true,"description":"Superseded by `permission_details`, which carries these same strings plus\ntheir display metadata; this field is slated for removal in the next major\nversion. It is not yet marked `deprecated` because clients cannot migrate\nuntil Agora populates `permission_details` — do that first, then flip the\noption, then remove the field."},"permission_description":{"type":"string","description":"Description of the permissions granted by this role."},"custom":{"type":"boolean","description":"True when this entry is a workspace-scoped custom role rather than a\nsystem-defined role template. Lets clients tell the two apart without\nparsing `name`."},"permission_details":{"type":"array","items":{"$ref":"#/components/schemas/v1RolePermission"},"description":"The permissions this role grants, with the display metadata needed to render\nthem. Supersedes `permissions`, which carries the same strings without it.\n\n`RolePermission.permission` is self-sufficient — it is the same\n\"{action}:{resource_path}\" string — so a client needs only this field.\n\nKeyed by the permission string rather than positional: entries correspond to\n`permissions` by `RolePermission.permission`, not by index. An entry may be\nabsent when a permission has no backing template metadata, so a client must\nfall back to the raw `permissions` string rather than assume coverage.","readOnly":true}},"description":"A Role represents a concrete, assignable role that can be assigned to users.\nRoles can be created from RoleTemplates or as standalone custom roles.","required":["title"]},"v1RolePermission":{"type":"object","properties":{"permission":{"type":"string","title":"The permission this describes, matching an entry in `Role.permissions`.\nFormat: \"{action}:{resource_path}\" (e.g., \"GET:/api/v1/me\")"},"display_name":{"type":"string","description":"Human-readable name of the permission (e.g., \"me:read\").\nMirrors the permission template's display name."},"description":{"type":"string","description":"What this permission allows. May be empty; not every template sets one."}},"description":"Display metadata for one permission a role grants.\n\nCarries only the human-readable name and description: the action and resource\npath are already encoded in the `Role.permissions` string this joins to, so\nrepeating them would double the payload of the field it describes for no gain."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/roles":{"get":{"summary":"List Organization Roles","operationId":"ListOrganizationRoles","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListOrganizationRolesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of roles to return.\nIf unspecified, at most 50 roles will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"A page token, received from a previous ListOrganizationRoles call.\nProvide this to retrieve the subsequent page.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Organizations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/users

> List Organization Users

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListOrganizationUsersResponse":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/v1UserWithRoles"},"description":"The list of users in the organization with their roles."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`ListOrganizationUsers` to get the next page of results. If this field is\nempty, it means there are no more results."}},"description":"Response message for listing users in an organization."},"v1UserWithRoles":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/v1UserBasicInfo"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1RoleBasicInfo"},"description":"The user's assigned roles.\nEach role includes its scope (organization or workspace)."},"workspace_ids":{"type":"array","items":{"type":"string"},"description":"IDs of workspaces in which the user has any active workspace-scoped role.\nEmpty if the user only holds org-scoped roles (which grant implicit access\nto all workspaces in the org). Used by Org-Settings Users tab to render the\n\"Workspaces\" column (\"2 workspaces\" / \"All workspaces\" / specific name)."}},"description":"A user with their assigned roles.\nThis type is reusable for both organization and workspace user listing APIs.\nThe RoleScope field in each role indicates whether the role is org-level or workspace-level."},"v1UserBasicInfo":{"type":"object","properties":{"name":{"type":"string","title":"The unique resource name of the user basic info.\nFormat: `organizations/{organization}/users/{user_basic_info}`"},"display_name":{"type":"string","description":"The user's display name."},"email":{"type":"string","description":"The user's email address."},"last_active_time":{"type":"string","format":"date-time","description":"The most recent timestamp the user was seen on an authenticated request.\nOutput-only; written debounced on auth events, so it is accurate to within\na few minutes rather than to the request.\nUnset when the user has not been seen since the field was introduced —\nthere is no backfill, so clients should render an em-dash rather than an epoch date.\nMirrors `User.last_active_time`; surfaced here so the Org/Workspace Settings\nUsers tables can render the \"Last active\" column from a single list call.","readOnly":true}},"description":"Contains basic information about a user.\nThis is a lightweight representation used when full user details are not needed."},"v1RoleBasicInfo":{"type":"object","properties":{"name":{"type":"string","description":"The role name (e.g., \"workspace-admin\", \"org-admin\", or custom role name)."},"role_scope":{"$ref":"#/components/schemas/v1RoleScope"}},"title":"Lightweight role information following the UserBasicInfo pattern.\nNote: RoleScope is imported from rbac.proto"},"v1RoleScope":{"type":"string","enum":["ROLE_SCOPE_UNSPECIFIED","ROLE_SCOPE_ORGANIZATION","ROLE_SCOPE_WORKSPACE"],"default":"ROLE_SCOPE_UNSPECIFIED","description":"Defines the scope at which a role can be applied.\n\n - ROLE_SCOPE_UNSPECIFIED: Unspecified role scope.\n - ROLE_SCOPE_ORGANIZATION: Role applies at the organization level.\n - ROLE_SCOPE_WORKSPACE: Role applies at the workspace level."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/users":{"get":{"summary":"List Organization Users","operationId":"ListOrganizationUsers","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListOrganizationUsersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of users to return.\nIf unspecified, at most 50 users will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page_token","description":"A page token, received from a previous `ListOrganizationUsers` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListOrganizationUsers` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter string following AIP-160 filtering standards.\nSupported filter fields:\n- `display_name`: Filter by display name (case-insensitive partial match). Example: `display_name:\"john\"`\n- `email`: Filter by email address (case-insensitive partial match). Example: `email:\"kognitos.com\"`\n- `role`: Filter by role name (exact match, case-insensitive). Example: `role=\"Organization Admin\"`\n- `role_scope`: Filter by role scope. Values: \"organization\" or \"workspace\". Example: `role_scope=organization`\n- `last_active_time`: Filter by last-active timestamp range using `>=`, `>`, `<=` or `<`\n  against an RFC3339 timestamp. Example: `last_active_time >= \"2026-07-01T00:00:00Z\"`\n  Users with no last-active value are excluded by any range bound.\nFilters can be combined with AND: `display_name:\"john\" AND role=\"Admin\"`","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Optional comma-separated list of fields to order by, following AIP-132.\nSupported fields: display_name, email, created_time, updated_time, last_active_time\nExample: \"display_name asc\", \"created_time desc\"\nDefault ordering is by created_time descending if not specified.\nUsers with no `last_active_time` sort as least-recently-active: last under\n`last_active_time desc`, first under `last_active_time asc`.","in":"query","required":false,"schema":{"type":"string"}},{"name":"include_deactivated","description":"When true, includes deactivated (soft-deleted) users in the response.\nDefaults to false. Returned rows will have `User.state = USER_STATE_DEACTIVATED`.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Organizations"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/users/{user\_id}

> Get User Basic Info

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UserBasicInfo":{"type":"object","properties":{"name":{"type":"string","title":"The unique resource name of the user basic info.\nFormat: `organizations/{organization}/users/{user_basic_info}`"},"display_name":{"type":"string","description":"The user's display name."},"email":{"type":"string","description":"The user's email address."},"last_active_time":{"type":"string","format":"date-time","description":"The most recent timestamp the user was seen on an authenticated request.\nOutput-only; written debounced on auth events, so it is accurate to within\na few minutes rather than to the request.\nUnset when the user has not been seen since the field was introduced —\nthere is no backfill, so clients should render an em-dash rather than an epoch date.\nMirrors `User.last_active_time`; surfaced here so the Org/Workspace Settings\nUsers tables can render the \"Last active\" column from a single list call.","readOnly":true}},"description":"Contains basic information about a user.\nThis is a lightweight representation used when full user details are not needed."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/users/{user_id}":{"get":{"summary":"Get User Basic Info","operationId":"GetUserBasicInfo","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UserBasicInfo"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Organizations"]}}}}
```

## Current User

> Gets the current authenticated user.\
> This is a singleton resource that represents the currently authenticated user.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CurrentUserResponse":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/v1User"}},"description":"Response message for the `CurrentUser` method."},"v1User":{"type":"object","properties":{"name":{"type":"string","description":"The unique resource name of the user.\nFormat: `users/{user}`\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"display_name":{"type":"string","description":"The user's display name."},"email":{"type":"string","description":"The user's email address. This is required and unique."},"provider_id":{"type":"string","description":"The identifier provided by the authentication provider (e.g., Auth0 user ID).\nThis field is used to link the user account with external authentication systems."},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the user was created.\nThis is an output-only field, populated by the server.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the user was last updated.\nThis is an output-only field, populated by the server.","readOnly":true},"onboarding_state":{"$ref":"#/components/schemas/v1OnboardingState"},"last_org":{"type":"string","title":"The resource name of the last organization viewed by the user.\nFormat: `organizations/{organization}`"},"last_workspace":{"type":"string","title":"The resource name of the last workspace viewed by the user.\nFormat: `organizations/{organization}/workspaces/{workspace}`"},"avatar_data_uri":{"type":"string","description":"The user's profile avatar as a data URI following RFC 2397. (MAN-3387)\nFormat: data:[<mediatype>][;encoding],<data>\nExample: data:image/png;encoding,<encoded-image-data>\nServer-side max payload size: 1MB."},"state":{"$ref":"#/components/schemas/v1UserState"},"last_active_time":{"type":"string","format":"date-time","description":"The most recent timestamp the user was seen (token validation / CurrentUser call). (MAN-3390)\nOutput-only; written debounced on auth events.","readOnly":true}},"description":"A user resource in the system.","required":["display_name","email"]},"v1OnboardingState":{"type":"string","enum":["ONBOARDING_STATE_UNSPECIFIED","WORKSPACE_CREATION_PENDING","COMPLETED"],"default":"ONBOARDING_STATE_UNSPECIFIED","description":"Represents the onboarding state of a user.\n\n - ONBOARDING_STATE_UNSPECIFIED: Unspecified onboarding state.\n - WORKSPACE_CREATION_PENDING: User needs to create a workspace.\n - COMPLETED: User has completed onboarding."},"v1UserState":{"type":"string","enum":["USER_STATE_UNSPECIFIED","USER_STATE_ACTIVE","USER_STATE_DEACTIVATED"],"default":"USER_STATE_UNSPECIFIED","description":"Today's flow re-uses the existing soft-delete column rather than introducing\na new column: `state = DEACTIVATED` iff `deleted_at IS NOT NULL`. Surfaced\noutput-only so admin UIs can render a \"Deactivated\" badge alongside the\nuser row.\n\n - USER_STATE_UNSPECIFIED: Unspecified — older clients that don't populate the field.\n - USER_STATE_ACTIVE: User is active.\n - USER_STATE_DEACTIVATED: User has been deactivated (soft-deleted). Authentication is blocked.","title":"User activation state, derived from `users.deleted_at`. (MAN-3390)"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/me":{"get":{"summary":"Current User","description":"Gets the current authenticated user.\nThis is a singleton resource that represents the currently authenticated user.","operationId":"CurrentUser","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CurrentUserResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"tags":["Organizations"]}}}}
```

## Current User Organization Roles

> Returns the current authenticated user's roles in an organization.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CurrentUserOrganizationRolesResponse":{"type":"object","properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1Role"},"description":"List of roles the current user has in the organization."}},"description":"Response message for CurrentUserOrganizationRoles."},"v1Role":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the role.\nFormat: organizations/{organization}/roles/{role} (org-level)\nFormat: organizations/{organization}/workspaces/{workspace}/roles/{role} (workspace-level)","description":"List responses also use this message for entries that are not concrete\nrole instances, in which case `name` carries the referenced resource:\n  roleTemplates/{role_template} for system-defined templates\n  organizations/{organization}/workspaces/{workspace}/customRoles/{custom_role}\n    for workspace custom roles, which additionally set `custom`.\nThese are not declared as patterns above because AIP-123 requires every\npattern's final segment to contain this resource's own singular."},"title":{"type":"string","description":"Human-readable title of the role (e.g., \"Administrator\", \"Editor\")."},"description":{"type":"string","description":"Description of what this role grants."},"permissions":{"type":"array","items":{"type":"string"},"title":"List of permission strings this role grants.\nFormat: \"{action}:{resource_path}\" (e.g., \"GET:/api/v1/me\")","readOnly":true,"description":"Superseded by `permission_details`, which carries these same strings plus\ntheir display metadata; this field is slated for removal in the next major\nversion. It is not yet marked `deprecated` because clients cannot migrate\nuntil Agora populates `permission_details` — do that first, then flip the\noption, then remove the field."},"permission_description":{"type":"string","description":"Description of the permissions granted by this role."},"custom":{"type":"boolean","description":"True when this entry is a workspace-scoped custom role rather than a\nsystem-defined role template. Lets clients tell the two apart without\nparsing `name`."},"permission_details":{"type":"array","items":{"$ref":"#/components/schemas/v1RolePermission"},"description":"The permissions this role grants, with the display metadata needed to render\nthem. Supersedes `permissions`, which carries the same strings without it.\n\n`RolePermission.permission` is self-sufficient — it is the same\n\"{action}:{resource_path}\" string — so a client needs only this field.\n\nKeyed by the permission string rather than positional: entries correspond to\n`permissions` by `RolePermission.permission`, not by index. An entry may be\nabsent when a permission has no backing template metadata, so a client must\nfall back to the raw `permissions` string rather than assume coverage.","readOnly":true}},"description":"A Role represents a concrete, assignable role that can be assigned to users.\nRoles can be created from RoleTemplates or as standalone custom roles.","required":["title"]},"v1RolePermission":{"type":"object","properties":{"permission":{"type":"string","title":"The permission this describes, matching an entry in `Role.permissions`.\nFormat: \"{action}:{resource_path}\" (e.g., \"GET:/api/v1/me\")"},"display_name":{"type":"string","description":"Human-readable name of the permission (e.g., \"me:read\").\nMirrors the permission template's display name."},"description":{"type":"string","description":"What this permission allows. May be empty; not every template sets one."}},"description":"Display metadata for one permission a role grants.\n\nCarries only the human-readable name and description: the action and resource\npath are already encoded in the `Role.permissions` string this joins to, so\nrepeating them would double the payload of the field it describes for no gain."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/me/organizations/{organization_id}/roles":{"get":{"summary":"Current User Organization Roles","description":"Returns the current authenticated user's roles in an organization.","operationId":"CurrentUserOrganizationRoles","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CurrentUserOrganizationRolesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Organizations"]}}}}
```
