> ## Documentation Index > Fetch the complete documentation index at: https://docs.tallychannel.com/llms.txt > Use this file to discover all available pages before exploring further. # Add or Update Principal > Creates or updates a principal's roles and flags within the tenant. Uses PATCH semantics — omitted fields are left unchanged. Requires `account_admin` tenancy role. At least one of `tenancy_role`, `api_functional_role`, `allow_counterparty_access`, or `principal_type` must be supplied. **`allow_counterparty_access: true`** may only be set by a caller whose own `principal_type` is `human`. Service account and AI agent callers are rejected with 422. Revoking (setting `false`) has no human-caller requirement. **`api_functional_role: tenant_owner`** may only be assigned to principals with `principal_type: human`. ## OpenAPI ````yaml PUT /v1/tenants/{tenant_id}/principals/{principal_id} openapi: 3.1.0 info: title: Tally Platform API version: '1.0' description: > The Tally Platform API is a versioned REST API for managing business identity state, counterparty access grants, and refresh workflows. All tenant-scoped endpoints require an `Authorization: Bearer ` header containing a valid Firebase Auth JWT. Tokens are issued by Google Identity Platform (GCIP) after sign-in at your environment's app domain. **Base URLs** | Environment | URL | |-------------|-----| | Staging | `https://tally-platform-api-xwka6vu2kq-ue.a.run.app` | | Production | `https://tally-platform-api-iikaevm4pq-ue.a.run.app` | contact: email: support@tallychannel.com servers: - url: https://tally-platform-api-xwka6vu2kq-ue.a.run.app description: Staging - url: https://tally-platform-api-iikaevm4pq-ue.a.run.app description: Production security: - BearerAuth: [] tags: - name: System description: Health checks and service metadata. No authentication required. - name: Tenants description: Tenant creation and member management. - name: Grants description: >- Access grant lifecycle — create, list, revoke. Controls which counterparty tenants can read which subjects. - name: Identity State description: >- Initial snapshot creation. Writes the first versioned state record for a subject. - name: Snapshots description: >- Read identity state — latest, history, by ID, export, chain proof, and diff. - name: Updates description: Propose and apply RFC 6902 patch updates to create new snapshot versions. - name: Transfer Offers description: Consensual `tenant_owner` role transfer handshake between principals. - name: Refresh Requests description: >- Counterparty-initiated requests for attribute updates or snapshot confirmation. - name: Webhooks description: Webhook subscription management and secret rotation. paths: /v1/tenants/{tenant_id}/principals/{principal_id}: put: tags: - Tenants summary: Add or update a tenant principal description: > Creates or updates a principal's roles and flags within the tenant. Uses PATCH semantics — omitted fields are left unchanged. Requires `account_admin` tenancy role. At least one of `tenancy_role`, `api_functional_role`, `allow_counterparty_access`, or `principal_type` must be supplied. **`allow_counterparty_access: true`** may only be set by a caller whose own `principal_type` is `human`. Service account and AI agent callers are rejected with 422. Revoking (setting `false`) has no human-caller requirement. **`api_functional_role: tenant_owner`** may only be assigned to principals with `principal_type: human`. operationId: upsertPrincipal parameters: - $ref: '#/components/parameters/tenant_id' - name: principal_id in: path required: true schema: type: string description: Principal ID in `oidc:{projectId}#{uid}` format. requestBody: required: true content: application/json: schema: type: object properties: tenancy_role: type: string enum: - account_admin - billing_admin - account_viewer nullable: true description: Set to `null` to remove the tenancy role. api_functional_role: type: string enum: - tenant_owner - tenant_admin - tenant_editor - tenant_proposer - tenant_reader nullable: true description: Set to `null` to remove the data-access role. principal_type: type: string enum: - human - service_account - ai_agent description: >- Defaults to `human` on first upsert. Required when registering a service account or AI agent. allow_counterparty_access: type: boolean description: >- Grants or revokes counterparty read access for this principal. Setting `true` requires the caller to have `principal_type human`. responses: '200': description: Principal updated or created. content: application/json: schema: $ref: '#/components/schemas/MemberRecord' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': description: Human-caller constraint violation or last-admin guard. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: parameters: tenant_id: name: tenant_id in: path required: true schema: type: string description: Tenant identifier. example: tally-staging schemas: MemberRecord: type: object properties: tenant_id: type: string principal_id: type: string tenancy_role: type: string enum: - account_admin - billing_admin - account_viewer nullable: true description: >- Account-level role. Controls membership administration (adding/removing principals, billing). api_functional_role: type: string enum: - tenant_owner - tenant_admin - tenant_editor - tenant_proposer - tenant_reader nullable: true description: >- Data-access role. Controls what the principal may do with subjects and grants. Ranked hierarchy — higher rank implies lower-rank permissions. principal_type: type: string enum: - human - service_account - ai_agent description: >- The kind of principal. Defaults to `human`. Used to enforce human-only constraints (e.g. `tenant_owner`, `allow_counterparty_access`). allow_counterparty_access: type: boolean description: >- When `true`, this principal may call counterparty-facing endpoints (accessible-subjects, grant-path snapshot reads). Defaults to `false`. May only be set to `true` by a human `account_admin`. status: type: string enum: - active - revoked created_at: type: string format: date-time ErrorEnvelope: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code. example: validation_error message: type: string description: Human-readable error message. example: Request body failed schema validation. details: type: array items: $ref: '#/components/schemas/ErrorDetail' request_id: type: string description: Request ID for tracing. Injected server-side. example: req_01j2k3m4n5 required: - code - message required: - error ErrorDetail: type: object properties: path: type: string description: JSON Pointer to the field that caused the error. example: /subject_id message: type: string example: subject_id is required. code: type: string example: invalid_type required: - path - message responses: ValidationError: description: Request body or parameter failed validation. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: validation_error message: Request body failed schema validation. details: - path: /subject_id message: subject_id is required. Unauthorized: description: Missing or invalid Bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unauthorized message: Authentication required. Forbidden: description: Authenticated but insufficient role or missing grant. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: forbidden message: Owner or grant required. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | Firebase Auth JWT issued by Google Identity Platform. Obtain a token by signing in at your app domain and calling `firebase.auth().currentUser.getIdToken()`. ````