nCino

nCino Role Permissions API

Endpoints for managing the >s assigned to a >. Permissions are identified by their string *key* (e.g. `manage_roles`). Requests are scoped to the authenticated token's company: a role that does not exist, or is owned by another company, returns a 404.

GitHub OpenAPI

Documentation

📖
Documentation
https://developer.ncinomortgage.com/mortgage/docs/getting-started
📖
APIReference
https://developer.ncinomortgage.com/mortgage/reference
📖
Authentication
https://developer.ncinomortgage.com/mortgage/docs/authentication-1
📖
Documentation
https://developer.ncinomortgage.com/mortgage/docs/webhooks
📖
Documentation
https://developer.ncino.com/e-vault/docs/getting-started
📖
APIReference
https://developer.ncino.com/e-vault/reference
📖
Authentication
https://developer.ncino.com/e-vault/docs/authentication

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/ncino/refs/heads/main/openapi/ncino-role-permissions-api-openapi.yml

Other Resources

🔗
Postman
https://api.ncinomortgage.com/developer_info/postman_collection/1.0
🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/ncino/refs/heads/main/asyncapi/ncino-mortgage-webhooks.yml

OpenAPI Specification

ncino-role-permissions-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: nCino Mortgage Role Permissions API
  description: API framework built from the ground up to be more a robust, forward thinking solution with tools to support our developer community
  version: '1.0'
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.ncinomortgage.com
  description: Production server
security:
- OAuth2: []
tags:
- name: Role Permissions
  description: 'Endpoints for managing the <<glossary:permission>>s assigned to a

    <<glossary:role>>.


    Permissions are identified by their string *key* (e.g. `manage_roles`).

    Requests are scoped to the authenticated token''s company: a role that

    does not exist, or is owned by another company, returns a 404.'
paths:
  /roles/{role_id}/permissions:
    get:
      tags:
      - Role Permissions
      operationId: role_permissions-index
      parameters:
      - name: role_id
        description: <<glossary:role>> ID.
        required: true
        in: path
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolePermissionsResult'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: '> 🚧 Under construction

        > **This endpoint is in beta.** Functionality may change without notice, support is limited, and use in production is not recommended. Your feedback is appreciated.


        Retrieve a role''s permissions


        Lists the permission keys currently enabled on the role.


        TODO: Remove the line below when endpoint is ready to go live for customers'
      summary: 🚧 Retrieve a role's permissions (BETA)
    post:
      tags:
      - Role Permissions
      operationId: role_permissions-create
      parameters:
      - name: role_id
        description: <<glossary:role>> ID.
        required: true
        in: path
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Updated permission keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolePermissionsResult'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          description: Unrecognized permission key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: '> 🚧 Under construction

        > **This endpoint is in beta.** Functionality may change without notice, support is limited, and use in production is not recommended. Your feedback is appreciated.


        Assign permissions to a role


        Adds the supplied permission keys to the role. Idempotent: keys already

        enabled on the role are left unchanged.


        TODO: Remove the line below when endpoint is ready to go live for customers'
      summary: 🚧 Assign permissions to a role (BETA)
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RolePermissionsBody'
    put:
      tags:
      - Role Permissions
      operationId: role_permissions-update
      parameters:
      - name: role_id
        description: <<glossary:role>> ID.
        required: true
        in: path
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Updated permission keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolePermissionsResult'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          description: Unrecognized permission key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: '> 🚧 Under construction

        > **This endpoint is in beta.** Functionality may change without notice, support is limited, and use in production is not recommended. Your feedback is appreciated.


        Replace a role''s permissions


        Replaces the role''s permission set with exactly the supplied keys.


        TODO: Remove the line below when endpoint is ready to go live for customers'
      summary: 🚧 Replace a role's permissions (BETA)
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RolePermissionsBody'
    delete:
      tags:
      - Role Permissions
      operationId: role_permissions-destroy
      parameters:
      - name: role_id
        description: <<glossary:role>> ID.
        required: true
        in: path
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Updated permission keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolePermissionsResult'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          description: Unrecognized permission key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: '> 🚧 Under construction

        > **This endpoint is in beta.** Functionality may change without notice, support is limited, and use in production is not recommended. Your feedback is appreciated.


        Remove permissions from a role


        Removes the supplied permission keys from the role. Idempotent: keys

        that are not currently enabled are ignored.


        TODO: Remove the line below when endpoint is ready to go live for customers'
      summary: 🚧 Remove permissions from a role (BETA)
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RolePermissionsBody'
components:
  responses:
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSet'
      headers:
        X-Api-Version:
          $ref: '#/components/headers/ApiVersionResponseHeader'
        X-Api-Supported-Versions:
          $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSet'
      headers:
        X-Api-Version:
          $ref: '#/components/headers/ApiVersionResponseHeader'
        X-Api-Supported-Versions:
          $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSet'
      headers:
        X-Api-Version:
          $ref: '#/components/headers/ApiVersionResponseHeader'
        X-Api-Supported-Versions:
          $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
    BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSet'
      headers:
        X-Api-Version:
          $ref: '#/components/headers/ApiVersionResponseHeader'
        X-Api-Supported-Versions:
          $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
  headers:
    ApiVersionResponseHeader:
      description: API version.
      schema:
        type: string
    ApiSupportedVersionsResponseHeader:
      description: API supported versions for endpoint.
      schema:
        type: string
  schemas:
    RolePermissionsResult:
      type: object
      properties:
        permission_keys:
          type: array
          items:
            type: string
          description: Current permission keys enabled on the role.
      required:
      - permission_keys
      description: The permission keys enabled on the role after the operation.
      additionalProperties: false
    RolePermissionsBody:
      type: object
      properties:
        permission_keys:
          type: array
          items:
            type: string
          description: Permission keys. On POST they are added to the role, on DELETE they are removed, and on PUT they replace the role's entire permission set.
      required:
      - permission_keys
      description: The permission keys to apply to a role.
      additionalProperties: false
    ErrorSet:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      required:
      - errors
      example:
        errors:
        - id: 123abc
          status: 400
          title: Generic title for the error
          detail: Detailed message for the error
          _links:
            resource: contextual resource if applicable
    Error:
      type: object
      properties:
        id:
          type: string
          description: A unique ID (useful as a reference when debugging an error with support)
        status:
          type: integer
          description: The HTTP status code
        title:
          type: string
          description: A generic title
        detail:
          type: string
          description: A detailed message
        _links:
          type: object
          description: A list of relevant links
      required:
      - id
      - status
      - title
      example:
        id: 123abc
        status: 400
        title: Generic title for the error
        detail: Detailed message for the error
        _links:
          resource: contextual resource if applicable
  parameters:
    ApiVersionHeader:
      name: X-Api-Version
      description: Specify API version, for example '1.0'. By default, the version configured in the company settings is used.
      required: false
      in: header
      schema:
        type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 Access Token (Default)
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}