> ## Documentation Index > Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a custom authorization role > Create a custom role from policy statements. The statements are stored as policy rules, but grant nothing until the role is assigned. ## OpenAPI ````yaml https://api.ravion.com/openapi.yaml post /authorization/roles openapi: 3.0.0 info: title: Ravion version: 0.0.0 servers: - url: https://api.ravion.com security: - BearerAuth: [] tags: - name: Projects - name: Environments - name: FeatureFlags - name: Pipelines - name: PipelineRuns - name: TerraformResources - name: TerraformExecutionSummaries - name: PipelineStepExecutions - name: AwsCloudWatch - name: PipelineVersions - name: Organizations - name: Stacks - name: StackWorkspaces - name: Auth - name: OAuth - name: User - name: Health - name: Memberships - name: ServiceAccounts - name: AwsDefaultNetworks - name: AwsAccounts - name: ApiKeys - name: AwsAmp - name: EksPrometheus - name: EksLoki - name: ExecutionEnvironments - name: ModuleDefinitions - name: ModuleCategories - name: ModuleVersions - name: ModuleInstances - name: DefaultValueDefinitions - name: DefaultValues - name: CodeSources - name: Github - name: Gitlab - name: Git - name: Values - name: Deployments - name: DeploymentResources - name: InfrastructureEvents - name: WebSocket - name: Domains - name: AcmCertificates - name: Describe - name: Reports - name: BillingPlans - name: BillingAccounts - name: BillingCycles - name: BillingUsageSummaries - name: BillingAddOns - name: BillingInvoices - name: Authorization paths: /authorization/roles: post: tags: - Authorization summary: Create a custom authorization role description: >- Create a custom role from policy statements. The statements are stored as policy rules, but grant nothing until the role is assigned. operationId: CreateAuthorizationRole requestBody: content: application/json: schema: additionalProperties: false properties: data: $ref: '#/components/schemas/CreateAuthorizationRoleData' required: - data type: object description: The body type of the operation request or response. required: true responses: '201': content: application/json: schema: additionalProperties: false properties: data: $ref: '#/components/schemas/AuthorizationRole' meta: $ref: '#/components/schemas/AuthorizationPolicyMeta' required: - data - meta type: object description: >- The request has succeeded and a new resource has been created as a result. '400': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The request is invalid or malformed. '401': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You are not authenticated '403': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You do not have permission to access this resource. '404': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The server cannot find the requested resource. '409': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The request conflicts with the current state of the server. '500': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Server error '503': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Service unavailable. components: schemas: CreateAuthorizationRoleData: additionalProperties: false properties: description: type: string expectedRevision: description: The policy revision this change is based on. format: int64 type: integer key: minLength: 1 type: string name: minLength: 1 type: string statements: items: $ref: '#/components/schemas/AuthorizationStatement' minItems: 1 type: array required: - key - name - statements - expectedRevision type: object AuthorizationRole: additionalProperties: false description: A reusable set of statements that grants nothing until assigned. properties: description: type: string id: type: string key: description: >- Unique key within the organization. Cannot reuse a system-managed role key. type: string name: type: string statements: items: $ref: '#/components/schemas/AuthorizationStatement' type: array required: - id - key - name - statements type: object AuthorizationPolicyMeta: additionalProperties: false description: Revision metadata returned with every authorization response. properties: policyRevision: description: >- The organization's policy revision after this request. Send it as `expectedRevision` on the next write. format: int64 type: integer required: - policyRevision type: object Errors.UserFacingErrorData: additionalProperties: false description: |- User-facing error presentation data. This is what the API returns to the frontend after formatting ErrorData using CEL templates from the error registry. Used for both: - Error fields on domain models (e.g., PipelineRun.error) - API error response bodies (HTTP 4xx/5xx responses) properties: action: allOf: - $ref: '#/components/schemas/Errors.Action' description: Optional action to help resolve the error code: description: Full error code, e.g., "Ravion:Pipeline:NOT_FOUND" type: string description: description: Additional description with more details type: string details: description: Structured details rendered as user-facing sections. items: $ref: '#/components/schemas/Errors.UserFacingErrorDetailSection' type: array isInternal: description: >- Indicates whether this error is internal (only set when ShowInternal=true). This allows SUPERADMINs to identify internal errors while viewing full details. type: boolean message: description: Main error message (required) type: string metadata: additionalProperties: {} description: >- Error params/metadata. Stripped for internal errors unless superadmin. type: object requestId: description: Request ID for correlating errors with server logs. type: string required: - code - message type: object AuthorizationStatement: additionalProperties: false description: >- One policy statement: an effect on actions over resources, optionally conditioned on attributes. properties: actions: description: Actions registered for `resource.type` in the authorization catalog. items: type: string minItems: 1 type: array conditions: description: Attribute conditions, all of which must match. items: $ref: '#/components/schemas/AuthorizationCondition' type: array effect: $ref: '#/components/schemas/AuthorizationEffect' givenId: allOf: - $ref: '#/components/schemas/GivenId' description: |- Optional name for the statement, unique within its role. When replacing statements, a statement without `id` keeps the stored statement with the same `givenId`. id: description: >- Statement ID, generated by Ravion. When replacing statements, send it back to keep a statement; omit it to add one. An ID that does not belong to the role is rejected. type: string resource: $ref: '#/components/schemas/AuthorizationResourceSelector' within: description: >- Resources the statement is limited to, each with everything under it, for example a project or an environment. Omit for the whole organization. Each must be of `resource.type` or a type that contains it, and exist when the statement is written; one deleted later just stops matching. At most 100. items: $ref: '#/components/schemas/AuthorizationScope' maxItems: 100 type: array required: - effect - actions - resource type: object Errors.Action: additionalProperties: false description: Action to help user resolve the error properties: label: description: Button/link label text type: string url: description: URL to navigate to for resolution type: string required: - label - url type: object Errors.UserFacingErrorDetailSection: additionalProperties: false description: Structured user-facing error detail section. properties: items: description: List of detail values for this section. items: type: string type: array object: additionalProperties: {} description: Structured detail payload for object rendering. type: object render: description: Rendering hint for clients. Valid values are list or object. type: string title: description: Detail section title shown in the UI. type: string required: - title - render type: object AuthorizationCondition: additionalProperties: false description: >- A resource attribute requirement. All conditions in a statement must match. properties: attribute: description: >- Attribute key, for example `environment` or `moduleDefinitionId`. Case-sensitive. minLength: 1 type: string operator: $ref: '#/components/schemas/AuthorizationConditionOperator' values: description: Accepted values. Case-sensitive. items: type: string minItems: 1 type: array required: - attribute - operator - values type: object AuthorizationEffect: description: >- Whether a statement grants or denies its actions. A matching deny overrides every allow. enum: - allow - deny type: string GivenId: description: User-provided identifier pattern used by all givenId fields maxLength: 60 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ type: string AuthorizationResourceSelector: additionalProperties: false description: The resources a statement applies to. properties: ids: description: >- Exact resource IDs. Omit to select every resource of `type` where the statement applies. items: type: string minItems: 1 type: array type: description: >- A resource type from the authorization catalog, for example `moduleInstance`. minLength: 1 type: string required: - type type: object AuthorizationScope: additionalProperties: false description: A resource a statement is limited to. properties: id: minLength: 1 type: string type: description: >- A resource type from the authorization catalog, for example `project`. minLength: 1 type: string required: - type - id type: object AuthorizationConditionOperator: description: >- How a condition compares an attribute: `equal` takes one value, `in` takes one or more. enum: - equal - in type: string securitySchemes: BearerAuth: scheme: Bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.