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

# Check Authorization for an Action

> Evaluate whether a user is authorized to perform a specific action on a resource.
The proxy path represents the original request path being authorized.




## OpenAPI

````yaml POST /api/v1/authorize/{proxy+}
openapi: 3.1.0
info:
  title: AuthZ Service API
  description: Authorization service for managing roles and user permissions
  version: 1.1.0
servers:
  - url: https://api.aion.xyz
    description: Production server
  - url: https://api.dev.internal.aion.xyz
    description: Staging server
security:
  - BearerAuth: []
tags:
  - name: Authorization
    description: Authorization check operations
  - name: Roles
    description: Operations related to role management
  - name: User Roles
    description: Operations related to user role queries
  - name: Role Assignments
    description: Operations for assigning, updating, and revoking roles
paths:
  /api/v1/authorize/{proxy+}:
    post:
      tags:
        - Authorization
      summary: Check authorization for an action
      description: >
        Evaluate whether a user is authorized to perform a specific action on a
        resource.

        The proxy path represents the original request path being authorized.
      operationId: authorize
      parameters:
        - name: proxy+
          in: path
          required: true
          description: >-
            The original request path being authorized (e.g.,
            "projects/my-project/instances")
          schema:
            type: string
            example: projects/my-project/instances
        - name: X-User-ID
          in: header
          required: true
          description: The user identifier making the request
          schema:
            type: string
            example: john.doe
        - name: X-Account-ID
          in: header
          required: true
          description: The account identifier for the request context
          schema:
            type: string
            example: my-company-account
        - name: X-Action
          in: header
          required: true
          description: >-
            The action being performed (e.g., "account:user:read",
            "project:instance:create")
          schema:
            type: string
            example: project:instance:create
      responses:
        '200':
          description: Authorization allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
              example:
                allowed: true
                reason: User has project_admin role
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Authorization denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
              example:
                allowed: false
                reason: User does not have permission to perform this action
components:
  schemas:
    AuthorizationResponse:
      type: object
      properties:
        allowed:
          type: boolean
          description: Whether the action is authorized
          example: true
        reason:
          type: string
          description: Explanation for the authorization decision
          example: User has account_admin role
      required:
        - allowed
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: BAD_REQUEST
            message:
              type: string
              description: Error message
              example: Invalid request parameters
            details:
              type: array
              items:
                type: string
              description: Additional error details
              example:
                - projectId is required for PROJECT scoped roles
          required:
            - code
            - message
      required:
        - error
  responses:
    BadRequest:
      description: Bad request - Invalid input parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: BAD_REQUEST
              message: Invalid request parameters
              details:
                - accountId must be a valid identifier
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token authentication

````