> ## Documentation Index > Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt > Use this file to discover all available pages before exploring further. # Grant a role on an organization > Grants a user or identity a role across the organization. You can grant only roles whose permissions you hold yourself; the platform role cannot be granted. Granting an identity a permission it did not hold revokes its existing tokens, and the response says how many. A user must already hold a role in the organization, at organization level or on any of its projects. Anyone else joins by accepting an invitation (`POST /v1/invitations`). ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/organizations/{id}/iam-bindings openapi: 3.1.0 info: title: Qumo Deploy REST API description: > The Qumo Deploy control plane: organizations, projects, signing keys, machine identities, access control, audit and billing. Relay credentials are not issued here: your app signs them with its own [signing keys](/guides/signing-keys). Every operation here is generated against the routes the server registers and checked in CI, so an operation in this reference exists and a route missing from it is deliberately internal (relay mesh, webhooks, probes, operator-only and browser sign-in routes). Errors are JSON objects with one `error` field. What each status code means is in [Error codes](/guides/error-codes); the token scope each permission needs is in [Scopes and permissions](/guides/scopes-permissions). version: 1.0.0 servers: - url: https://api.qumo-deploy.com description: Public API (Bearer tokens only; cookies are ignored) security: [] tags: - name: Account description: The signed-in user's own sessions, tokens, security settings and data. - name: Device flow description: OAuth 2.0 device authorization, used by `qumod login`. - name: Organizations description: Organizations, their members and usage. - name: Projects description: Projects inside an organization. - name: Signing keys description: Keys your app signs relay credentials with. - name: Relays description: Where clients of a broadcast path connect. - name: Identities description: Machine identities, their tokens and IP allowlists. - name: Access control description: Roles, IAM bindings and invitations. - name: Audit description: The audit log and its webhook. - name: Notifications description: Notification policies. - name: Billing description: Plans, usage cost, budgets, invoices and payment methods. - name: Pricing description: Public price list. paths: /v1/organizations/{id}/iam-bindings: post: tags: - Access control summary: Grant a role on an organization description: | Grants a user or identity a role across the organization. You can grant only roles whose permissions you hold yourself; the platform role cannot be granted. Granting an identity a permission it did not hold revokes its existing tokens, and the response says how many. A user must already hold a role in the organization, at organization level or on any of its projects. Anyone else joins by accepting an invitation (`POST /v1/invitations`). operationId: createOrganizationIamBinding parameters: - name: id in: path required: true description: The organization's id. schema: type: string format: uuid example: 3f8c2a1e-7b4d-4e9a-9c61-2d5e8f0a1b7c requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IamBindingCreateRequest' responses: '201': description: The created binding. content: application/json: schema: $ref: '#/components/schemas/IamBindingGrant' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': description: | The user holds no role in the organization, or the user id names nobody: both get this same answer. Nothing was granted. Invite them with `POST /v1/invitations` instead. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'user is not a member of this organization: invite them instead' security: - token: [] - cliSession: [] - sessionCookie: [] csrfToken: [] components: schemas: IamBindingCreateRequest: type: object required: - principal_type - principal_id - role_id properties: principal_type: type: string enum: - user - identity example: user principal_id: type: string format: uuid description: The user's or identity's id. example: 5e7a9c3b-1d2f-4b6e-8a0c-7f3d9e1b5a24 role_id: type: string description: | The role to grant. `roles/platform.admin` is never grantable, and `roles/organization.admin` only on an organization. enum: - roles/project.viewer - roles/project.editor - roles/project.admin - roles/organization.admin example: roles/project.editor IamBindingGrant: description: The binding a grant created, and what the grant revoked. allOf: - $ref: '#/components/schemas/IamBinding' - type: object properties: revoked_identity_tokens: type: integer minimum: 1 description: | How many of the identity's tokens the grant revoked, because it gave the identity a permission it did not hold. Absent when none were. Mint a new token after such a grant. example: 2 Error: type: object required: - error properties: error: type: string description: A human-readable message. example: organization_id is required IamBinding: type: object description: A role granted to a principal at a scope. required: - id - principal_type - principal_id - role_id - scope_type - scope_id properties: id: type: string format: uuid example: 1a3c5e7f-9b2d-4f6a-8e0c-2d4f6a8b0c1e principal_type: type: string enum: - user - identity example: user principal_id: type: string description: The user's or identity's id. example: 5e7a9c3b-1d2f-4b6e-8a0c-7f3d9e1b5a24 principal_name: type: string description: >- The user's or identity's name, in lists. Absent when the principal no longer exists. example: Hanako Yamada principal_email: type: string description: The user's email, in lists. Absent for identities. example: hanako@example.com role_id: type: string example: roles/project.editor scope_type: type: string enum: - project - organization - platform example: project scope_id: type: string format: uuid description: The project's or organization's id; the nil UUID for platform scope. example: 9b1d6e2f-4a3c-4f8b-a7e5-0c9d2b4f6e81 responses: BadRequest: description: >- Malformed request or failed validation. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Authenticated but not allowed (permission, token scope, IP allowlist or CSRF). See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: token: type: http scheme: bearer bearerFormat: qumo_pat_ description: > A personal access token (`POST /v1/auth/tokens`) or a machine identity token (`POST /v1/projects/{project_id}/identities/{identity_id}/tokens`), both prefixed `qumo_pat_`. A token's scopes cap what it can do; see [Scopes and permissions](/guides/scopes-permissions). A personal token names no organization: on a route whose path names no project or organization, pass `?organization_id=`. cliSession: type: http scheme: bearer description: | The session token `qumod login` obtains through the device flow (`POST /v1/auth/device/token`). It acts as the signed-in user, like a console session, and needs no CSRF token. sessionCookie: type: apiKey in: cookie name: __Host-qumo_session description: | The console's browser session. Accepted only on the console origin (`https://console.qumo-deploy.com`), never on `api.qumo-deploy.com`. A request that changes state must also send `X-CSRF-Token`. csrfToken: type: apiKey in: header name: X-CSRF-Token description: | CSRF token paired with `sessionCookie` on POST, PUT, PATCH and DELETE. Bearer requests do not send it. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.