> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Revoke a register role from a caller

> Revoke a register role from a caller



## OpenAPI

````yaml openapi.bundled.yaml POST /v2/register/roles/revoke
openapi: 3.1.0
info:
  title: Parmana API
  version: 1.0.0
  description: >
    Parmana sits between an AI agent and the systems it acts on. An agent sends
    a Business Transaction: who

    authorized it, what action it wants, and the facts that justify it. Parmana
    evaluates the policy bound to

    the action, checks any signed human approval the policy requires, releases
    the action to the connector

    only if the policy approves, and returns a signed Execution Trust Record
    anyone can verify.


    **Authentication.** Send `Authorization: Bearer <key>` on every request. The
    only routes that need no key

    are the probes, the documents and the independent verification routes: `GET
    /health`, `GET /ready`,

    `GET /openapi.yaml`, `GET /openapi.json`, `GET /api-manifest.json`, `GET
    /documentation`,

    `GET /reference`, `GET /parmana-handbook.pdf`, `GET
    /handbook/download-leads`,

    `POST /handbook/download-leads`, `POST /refusal/verify`, `POST
    /execution-intents/verify`,

    `POST /audit/verify`, `GET /keys/{keyId}` and `GET /.well-known/jwks.json`.
    A missing or unknown key

    returns `401` before anything else runs. The server holds only a hash of
    each key. See

    [Authentication](/api-reference/authentication).


    **Two kinds of key.** An agent or service key may invoke only the
    capabilities listed on it. A human key

    (`credentialHolderType: USER`) is required for governance: proposing and
    approving policies, approvers

    and external connectors, and repairing Execution Intents. Approving or
    rejecting a change also needs a

    step up authorization signed with the checker's own step up key, and the
    checker must not be the

    person who proposed it.


    **Ownership.** Every lookup by `businessTransactionId` is scoped to the key
    that submitted the

    transaction. A transaction submitted by another key returns the same `404`
    as one that does not exist.


    **Try it live.** The "Try it" panels call production,
    `https://parmana-api-real.vercel.app`, with whatever key

    you enter. There is no public sandbox yet, so do not send test data through
    these panels.


    **Start here:** the [Quickstart](/quickstart), then [Integrate
    Parmana](/agents/integrate) for agents

    and [Connect any external system](/guides/connect-any-external-system) for
    your own endpoint.
  contact:
    name: Parmana Systems
    email: founder@parmanasystems.com
  license:
    name: Apache License 2.0, see LICENSE
    url: https://docs.parmanasystems.com/license
servers:
  - url: https://parmana-api-real.vercel.app
    description: Production. Needs a key issued by the operator.
  - url: http://localhost:3000
    description: Local (packages/api, PORT env var, default 3000)
security:
  - bearerAuth: []
tags:
  - name: Execution
    description: >-
      Executes a Business Transaction through the complete Execution Trust
      pipeline
  - name: Transactions
    description: Business Transaction creation and retrieval
  - name: Verification
    description: Deterministic verification of an Execution Trust Record
  - name: Receipts
    description: Cryptographically signed Execution Trust Receipts
  - name: Trust Records
    description: Execution Trust Record retrieval
  - name: Replay
    description: Deterministic replay of a recorded Execution Trust Record
  - name: Policies
    description: Policy existence/readability check
  - name: Policy Governance
    description: Maker-checker proposal, listing, approval, and rejection of policy changes
  - name: Approvers
    description: Maker-checker for the keys trusted to sign approvals, without a deploy
  - name: External Connectors
    description: >-
      Maker-checker for binding a capability to an operator's HTTPS endpoint and
      its policy, without a deploy (ADR-0013)
  - name: Policy v2 (experimental)
    description: >-
      EXPERIMENTAL. Policy version 2 decisions, reviews, the register, console
      and notification endpoints. Mounted only when the deployment enables
      policy version 2. Shapes may change in a minor release until promoted.
  - name: Business Signal Sources
    description: >-
      Maker-checker for the business systems Parmana asks for the facts a policy
      needs, without a deploy (RFC-0023)
  - name: Authority Grants
    description: >-
      Maker-checker for which agent may have which action decided, within which
      limits, until when (RFC-0023)
  - name: Sandbox
    description: Routes that exist only in sandbox mode, not on production
  - name: Kill Switch
    description: >-
      Operator kill switch (ADR-0017). Trip and reset need the operator
      capabilities, and probe results need the probe capability; status is open
      to any authenticated caller
  - name: Refusal Records
    description: >-
      Durable, signed evidence that a policy decision rejected a transaction
      (RFC-0021)
  - name: Execution Intents
    description: >-
      A signed statement, stored before an action is released, of exactly what
      is about to be released, plus the operator tools to find and repair a
      released action that has no signed Trust Record (ADR-0012)
  - name: Audit
    description: >-
      Signed caller-authentication audit events, independently
      third-party-verifiable
  - name: System
    description: Operational endpoints
paths:
  /v2/register/roles/revoke:
    post:
      tags:
        - Policy v2 (experimental)
      summary: Revoke a register role from a caller
      operationId: policyV2RevokeRole
      requestBody:
        $ref: '#/components/requestBodies/PolicyV2RoleGrant'
      responses:
        '200':
          $ref: '#/components/responses/PolicyV2RegisterChange'
        '400':
          $ref: '#/components/responses/PolicyV2InvalidRequest'
        '401':
          $ref: '#/components/responses/PolicyV2Unauthenticated'
        '403':
          $ref: '#/components/responses/PolicyV2Forbidden'
        '409':
          $ref: '#/components/responses/PolicyV2Conflict'
        '422':
          $ref: '#/components/responses/PolicyV2Refused'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            # EXPERIMENTAL Policy version 2. Available only where the deployment
            enables it.

            # Revoke a role

            curl -X POST
            "https://parmana-api-real.vercel.app/v2/register/roles/revoke" \
              -H "Authorization: Bearer $PARMANA_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"callerId":"caller-ops-1","role":"reviewer"}'
        - lang: typescript
          label: TypeScript
          source: >-
            // EXPERIMENTAL Policy version 2. Available only where the
            deployment enables it.

            // Revoke a role

            const response = await fetch(
              "https://parmana-api-real.vercel.app/v2/register/roles/revoke",
              {
                method: "POST",
                headers: {
                  Authorization: `Bearer ${process.env.PARMANA_API_KEY}`,
                  "Content-Type": "application/json",
                },
                body: JSON.stringify({ callerId: "caller-ops-1", role: "reviewer" }),
              },
            );

            console.log(response.status, await response.text());
        - lang: python
          label: Python
          source: >-
            # EXPERIMENTAL Policy version 2. Available only where the deployment
            enables it.

            # Revoke a role

            import json

            import os

            import urllib.request


            BODY = r'{"callerId":"caller-ops-1","role":"reviewer"}'



            def main() -> None:
                request = urllib.request.Request(
                    "https://parmana-api-real.vercel.app/v2/register/roles/revoke",
                    data=json.dumps(json.loads(BODY)).encode("utf-8"),
                    method="POST",
                    headers={
                        "Authorization": "Bearer " + os.environ.get("PARMANA_API_KEY", ""),
                        "Content-Type": "application/json",
                    },
                )
                with urllib.request.urlopen(request) as response:
                    print(response.status, response.read().decode("utf-8"))


            if __name__ == "__main__":
                main()
components:
  requestBodies:
    PolicyV2RoleGrant:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - callerId
              - role
            properties:
              callerId:
                type: string
              role:
                type: string
                enum:
                  - second-approver
                  - risk-function
                  - parmana-owner
                  - source-owner
                  - action-owner
                  - gate-owner
                  - reviewer
                  - operator
  responses:
    PolicyV2RegisterChange:
      description: >-
        The register record the change produced (for example a source,
        threshold, action, policy version, approver key or role grant). The
        shape depends on the change (EXPERIMENTAL Policy v2 route).
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
          example:
            name: erp-ledger
            status: proposed
            proposedBy: caller-ops-1
            approvals: []
    PolicyV2InvalidRequest:
      description: >-
        The body or a parameter is not valid. The message names the field
        (EXPERIMENTAL Policy v2 route).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyV2Error'
          example:
            error: invalid_request
            message: capability must look like namespace:verb.
    PolicyV2Unauthenticated:
      description: No key, or an unknown key (EXPERIMENTAL Policy v2 route).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyV2Error'
          example:
            error: unauthenticated
    PolicyV2Forbidden:
      description: >-
        The caller's role does not allow this change or screen (EXPERIMENTAL
        Policy v2 route).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyV2Error'
          example:
            error: forbidden
            message: The caller does not hold a role that allows this change.
    PolicyV2Conflict:
      description: >-
        The state changed while it was being saved. Read it again and retry
        (EXPERIMENTAL Policy v2 route).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyV2Error'
          example:
            error: conflict
            message: >-
              The register changed while it was being saved. Read it again and
              retry.
    PolicyV2Refused:
      description: >-
        The change is refused by a rule of the register or the review. The
        message says why. A go-live refusal also lists `missing` (EXPERIMENTAL
        Policy v2 route).
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/PolicyV2Error'
              - type: object
                properties:
                  missing:
                    type: array
                    items:
                      type: string
          example:
            error: refused
            message: The action has no approved threshold.
            missing:
              - an approved threshold
    RateLimited:
      description: >-
        Too many requests from this caller on this route in the last minute. The
        default limits are 30 per caller per minute on `/execute`, 300 per IP
        address on `/health` and `/ready`, and 60 per IP address shared by the
        unauthenticated verification and handbook routes. The request never
        reached the handler, so nothing was recorded or executed. Wait the
        number of seconds in the `Retry-After` header, then retry.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.schema'
          examples:
            rateLimited:
              summary: Rate limit exceeded
              value:
                error: Rate limit exceeded. Try again later.
                code: RATE_LIMITED
  schemas:
    PolicyV2Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            A stable machine code, for example forbidden, refused,
            invalid_request, conflict, not_found, not_enabled, not_verified, or
            unauthenticated.
        message:
          type: string
    error.schema:
      title: Error Response
      description: >-
        Shared error envelope produced by
        packages/api/src/middleware/error-handler.ts and by every route's inline
        validation checks. error is always a plain human-readable string (never
        a nested object). code is present only when the failure was a
        RuntimeError subclass reaching the centralized error handler
        (VerificationFailedError, ReceiptGenerationError, or an uncategorized
        RuntimeError); it is absent from every inline route-level check
        (businessTransactionId format/required checks) and from
        BusinessTransactionValidationError, PolicyValidationError,
        SignalValidationError, PolicyNotFoundError,
        DuplicateBusinessTransactionError, and the generic 500 fallback. POST
        /policies/validate does NOT use this envelope at all. See its own
        response schema. For the triggering condition and recommended caller
        action behind any specific error/code/status combination, see the Error
        catalog at /api-reference/error-catalog.
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: >-
            Stable machine-readable error code. Only present for errors that
            reach the handler as a RuntimeError.
          examples:
            - RUNTIME_ERROR
            - VERIFICATION_FAILED
            - RECEIPT_GENERATION_FAILED
            - POLICY_DENIED
            - CAPABILITY_NOT_ALLOWED
            - RATE_LIMITED
            - AUDIT_UNAVAILABLE
            - SIGNING_UNAVAILABLE
            - CONNECTOR_NOT_REGISTERED
            - EXECUTION_RECORD_INCOMPLETE
            - EXECUTION_INTENT_UNAVAILABLE
            - EXECUTION_INTENT_RESULT_NOT_RECORDED
            - EXECUTION_INTENT_NOT_FOUND
            - EXECUTION_INTENTS_NOT_ENABLED
            - EXECUTION_INTENT_NOT_RESOLVABLE
            - EXECUTION_INTENT_RESOLUTION_INVALID
            - NON_HUMAN_CALLER_DENIED
            - EXECUTION_OUTCOME_UNKNOWN
            - AUTHORIZATION_NO_LONGER_VALID
        executionStatus:
          type: string
          enum:
            - EXECUTION_UNKNOWN
            - NOT_EXECUTED
          description: >-
            RFC-0023 phase 4. EXECUTION_UNKNOWN with EXECUTION_OUTCOME_UNKNOWN:
            the action was released and the call failed, so whether it ran is
            unknown; never reported as failed, and the Execution Intent stays
            ERRORED until a person resolves it. NOT_EXECUTED with
            AUTHORIZATION_NO_LONGER_VALID: the release was refused because a
            business condition or the authority grant it rested on no longer
            held, and nothing was sent.
      examples:
        - error: businessTransactionId must be a valid UUID.
        - error: >-
            Business Transaction 'eed2a972-1bf5-4166-8472-761f76fbf1b2' already
            exists.
        - error: >-
            Execution rejected: Vendor payment rejected because the assessed
            payment risk exceeds the maximum permitted threshold.
          code: RUNTIME_ERROR
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Caller API key issued by scripts/generate-api-key.ts. Sent as
        Authorization: Bearer <key>. Verified against a stored SHA-256 hash in
        constant time by packages/api/src/auth/StaticKeyAuthenticator.ts.
        Required on every route not listed as exempt in this document's
        top-level description. See /api-reference/authentication.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.