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

# Set Enforcement

> Move a grant along the rollout ladder.

Promotion and demotion both run through here. Demoting is a legitimate and
expected move — a canary whose refusal rate turns out to be wrong should go
back to observe rather than be switched off, because switching it off loses
the measurement that would tell you when it is ready.

**Who may call it:** governance-officer or admin. A workspace API key is refused here: this is an act that belongs to a named person.



## OpenAPI

````yaml /api/openapi.json post /v1/grants/{grant_id}/enforcement
openapi: 3.1.0
info:
  title: RotaGrant API
  version: 0.1.0
  description: >-
    The HTTP API of a RotaGrant deployment, made from the product's own route
    definitions at the commit named in `x-rotascale-source`. Nothing here is
    written by hand.


    There is no shared endpoint. RotaGrant runs in your environment, and your
    deployment serves its own copy of this description at `/api/docs`. That copy
    is the authority on what your version has and which features are switched
    on; this one is the reference for one commit of the main line. The version
    is 0.1.0: routes and shapes can still change.


    Every route says who may call it. Most need a bearer token from the identity
    provider your deployment uses, held by a person with the role named. The
    routes an SDK calls also accept a workspace API key. A few are open, and say
    why.
servers:
  - url: https://{deployment}
    description: Your own deployment. There is no shared endpoint.
    variables:
      deployment:
        default: rotagrant.internal.example
        description: The host your deployment answers on.
security: []
paths:
  /v1/grants/{grant_id}/enforcement:
    post:
      tags:
        - Authority
      summary: Set Enforcement
      description: >-
        Move a grant along the rollout ladder.


        Promotion and demotion both run through here. Demoting is a legitimate
        and

        expected move — a canary whose refusal rate turns out to be wrong should
        go

        back to observe rather than be switched off, because switching it off
        loses

        the measurement that would tell you when it is ready.


        **Who may call it:** governance-officer or admin. A workspace API key is
        refused here: this is an act that belongs to a named person.
      operationId: set_enforcement_v1_grants__grant_id__enforcement_post
      parameters:
        - name: grant_id
          in: path
          required: true
          schema:
            type: string
            title: Grant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoteIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - bearerToken: []
components:
  schemas:
    PromoteIn:
      properties:
        enforcement_mode:
          type: string
          pattern: ^(observe|shadow|canary|enforce)$
          title: Enforcement Mode
        canary_percent:
          anyOf:
            - type: integer
              maximum: 100
              exclusiveMinimum: 0
            - type: 'null'
          title: Canary Percent
        reason:
          type: string
          maxLength: 2000
          minLength: 1
          title: Reason
      type: object
      required:
        - enforcement_mode
        - reason
      title: PromoteIn
    GrantOut:
      properties:
        id:
          type: string
          title: Id
        enforcement_mode:
          type: string
          enum:
            - observe
            - shadow
            - canary
            - enforce
          title: Enforcement Mode
        canary_percent:
          anyOf:
            - type: integer
            - type: 'null'
          title: Canary Percent
        issued_against_provenance:
          anyOf:
            - type: string
            - type: 'null'
          title: Issued Against Provenance
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        kind:
          type: string
          title: Kind
        environment:
          anyOf:
            - type: string
            - type: 'null'
          title: Environment
        principal_type:
          type: string
          title: Principal Type
        principal_id:
          type: string
          title: Principal Id
        parent_grant_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Grant Id
        depth:
          type: integer
          title: Depth
        scope:
          additionalProperties:
            items:
              type: string
            type: array
          type: object
          title: Scope
        audience:
          anyOf:
            - type: string
            - type: 'null'
          title: Audience
        policy:
          anyOf:
            - type: string
            - type: 'null'
          title: Policy
        policy_rendering:
          anyOf:
            - type: string
            - type: 'null'
          title: Policy Rendering
        budget_amount_minor:
          anyOf:
            - type: integer
            - type: 'null'
          title: Budget Amount Minor
        budget_currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Budget Currency
        spent_amount_minor:
          type: integer
          title: Spent Amount Minor
        budget_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Budget Count
        spent_count:
          type: integer
          title: Spent Count
        held_amount_minor:
          type: integer
          title: Held Amount Minor
          default: 0
        held_count:
          type: integer
          title: Held Count
          default: 0
        created_at:
          type: string
          format: date-time
          title: Created At
        not_before:
          type: string
          format: date-time
          title: Not Before
        not_after:
          type: string
          format: date-time
          title: Not After
        conditions:
          additionalProperties: true
          type: object
          title: Conditions
        delegation_policy:
          type: string
          title: Delegation Policy
        status:
          type: string
          title: Status
        pending_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Pending Reason
        revoked_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Revoked At
        revoked_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Revoked By
        revoked_by_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Revoked By Email
        revocation_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Revocation Reason
      type: object
      required:
        - id
        - enforcement_mode
        - canary_percent
        - issued_against_provenance
        - agent_id
        - kind
        - environment
        - principal_type
        - principal_id
        - parent_grant_id
        - depth
        - scope
        - audience
        - policy
        - policy_rendering
        - budget_amount_minor
        - budget_currency
        - spent_amount_minor
        - budget_count
        - spent_count
        - created_at
        - not_before
        - not_after
        - conditions
        - delegation_policy
        - status
      title: GrantOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        A token from the identity provider your deployment federates with. It
        identifies a person; their roles in the workspace decide what they may
        do.

````

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