Quinyx Role API
The Role API from Quinyx — 2 operation(s) for role.
OpenAPI Specification
openapi: 3.1.0
info:
title: Quinyx Absence Schedules Role API
version: v2
x-service: absence-schedule
description: null
servers:
- url: https://api.quinyx.com
description: Production API
- url: https://api-rc.quinyx.com
description: RC API
tags:
- name: Role
paths:
/organization/v3/roles:
get:
summary: List roles
description: Returns a paginated list of roles.
operationId: getRoles
parameters:
- name: pageToken
in: query
description: Cursor for the next page of results.
required: false
schema:
type: string
example: eyJpZCI6MTAwfQ
- name: pageSize
in: query
description: Maximum number of items to return.
required: false
schema:
type: integer
format: int32
default: 50
example: 50
maximum: 100
minimum: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/security_CursorPageRoleResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/security_ProblemDetail'
- $ref: '#/components/schemas/security_ValidationError'
examples:
badRequestProblemDetail:
summary: Bad request
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
detail: The request is invalid or malformed
instance: /organization/v3/roles
badRequestValidationError:
summary: Bad request
description: Example ValidationError response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
errors:
- detail: name is mandatory
pointer: '#/name'
instance: /organization/v3/roles
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/security_ProblemDetail'
examples:
unauthorized:
summary: Unauthorized
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/unauthorized
title: Unauthorized
status: 401
detail: Access token not set or invalid, and the requested resource could not be returned
instance: /organization/v3/roles
'403':
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/security_ProblemDetail'
examples:
forbidden:
summary: Forbidden
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/forbidden
title: Forbidden
status: 403
detail: The resource could not be returned as the requestor is not authorized
instance: /organization/v3/roles
'500':
description: Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/security_ProblemDetail'
examples:
serverError:
summary: Server error
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/server-error
title: Server Error
status: 500
detail: The server encountered an unexpected error
instance: /organization/v3/roles
security:
- OAuth2ClientCredentials:
- organization:roles:read
x-audience: public
x-resource-group: Organization
x-resource: Role
tags:
- Role
/organization/v3/roles/{id}:
get:
summary: Get a role
description: Returns a role by ID.
operationId: getRole
parameters:
- name: id
in: path
required: true
schema:
description: An identifier that can be either a Quinyx ID or a prefixed external ID string.
oneOf:
- type: string
description: The Quinyx ID of the resource.
pattern: ^[0-9]+$
- type: string
description: The external string ID, which must start with 'xrefId:'.
example: xrefId:f47ac10b-58cc-4
pattern: ^xrefId:[a-zA-Z0-9._-]{1,64}$
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/security_RoleResponse'
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/security_ProblemDetail'
examples:
unauthorized:
summary: Unauthorized
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/unauthorized
title: Unauthorized
status: 401
detail: Access token not set or invalid, and the requested resource could not be returned
instance: /organization/v3/roles/{id}
'403':
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/security_ProblemDetail'
examples:
forbidden:
summary: Forbidden
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/forbidden
title: Forbidden
status: 403
detail: The resource could not be returned as the requestor is not authorized
instance: /organization/v3/roles/{id}
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/security_ProblemDetail'
examples:
notFound:
summary: Not found
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/not-found
title: Not Found
status: 404
detail: The requested resource was not found
instance: /organization/v3/roles/{id}
'500':
description: Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/security_ProblemDetail'
examples:
serverError:
summary: Server error
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/server-error
title: Server Error
status: 500
detail: The server encountered an unexpected error
instance: /organization/v3/roles/{id}
security:
- OAuth2ClientCredentials:
- organization:roles:read
x-audience: public
x-resource-group: Organization
x-resource: Role
tags:
- Role
components:
schemas:
security_ValidationErrorDetail:
type: object
description: A single validation error.
properties:
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem.
example: name is mandatory
pointer:
type: string
description: A JSON Pointer [RFC6901] to the associated entity in the request body.
example: '#/name'
security_CursorPageRoleResponse:
type: object
description: A page of data along with pagination information for cursor-based pagination.
properties:
data:
type: array
description: The data in the page.
items:
$ref: '#/components/schemas/security_RoleResponse'
maxItems: 100
pagination:
$ref: '#/components/schemas/security_CursorPaginationInfo'
security_RoleResponse:
type: object
description: Represents a role within the organization
properties:
id:
type: string
description: Unique identifier of the role
example: '42'
name:
type: string
description: The name of the role
example: Manager
xrefId:
type: string
description: External reference identifier
example: ext-role-123
levelId:
type: string
description: Identifier of the associated level (rank)
example: '5'
security_ProblemDetail:
type: object
description: RFC 9457 Problem Details for HTTP APIs
properties:
type:
type: string
description: A URI reference that identifies the problem type
example: https://developer.quinyx.com/api/problems/error-type
title:
type: string
description: A short, human-readable summary of the problem type
example: Error Title
status:
type: integer
format: int32
description: The HTTP status code
example: 404
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem
example: A detailed explanation of the error
instance:
type: string
description: A URI reference that identifies the specific occurrence of the problem
example: /api/endpoint
required:
- status
- title
- type
title: ProblemDetail
security_CursorPaginationInfo:
type: object
description: Pagination information for cursor-based pagination.
properties:
nextPageToken:
type: string
description: The token for the next page
example: eyJpZCI6MTIwfQ
previousPageToken:
type: string
description: The token for the previous page
example: eyJpZCI6ODB9
security_ValidationError:
type: object
description: Validation errors, conforming to RFC 9457.
properties:
type:
type: string
description: A URI reference that identifies the problem type
example: https://developer.quinyx.com/api/problems/validation-error
title:
type: string
description: A short, human-readable summary of the problem type.
example: The request is not valid.
status:
type: integer
format: int32
description: The HTTP status code
example: 422
errors:
type: array
description: A list of validation errors.
items:
$ref: '#/components/schemas/security_ValidationErrorDetail'
maxItems: 50
minItems: 1
instance:
type: string
description: A URI reference that identifies the specific occurrence of the problem.
example: /api/endpoint
required:
- errors
- status
- title
- type
title: ValidationError
securitySchemes:
employee_OAuth2ClientCredentials:
type: oauth2
description: OAuth2 Client Credentials flow. See https://developer.quinyx.com/api/authentication
flows:
clientCredentials:
tokenUrl: /oauth/v3/token
scopes:
hr:employees:create: ''
hr:employees:delete: ''
hr:employees:read: ''
hr:employees:update: ''
opening-hours_OAuth2ClientCredentials:
type: oauth2
description: OAuth2 Client Credentials flow. See https://developer.quinyx.com/api/authentication
flows:
clientCredentials:
tokenUrl: /oauth/v3/token
scopes: {}
organisation_OAuth2ClientCredentials:
type: oauth2
description: OAuth2 Client Credentials flow. See https://developer.quinyx.com/api/authentication
flows:
clientCredentials:
tokenUrl: /oauth/v3/token
scopes:
organization:groups:create: ''
organization:groups:delete: ''
organization:groups:read: ''
organization:groups:update: ''
rest-api-uaa_OAuth2ClientCredentials:
type: oauth2
description: OAuth2 Client Credentials flow. See https://developer.quinyx.com/api/authentication
flows:
clientCredentials:
tokenUrl: /oauth/v3/token
scopes: {}
schedule-availability_OAuth2ClientCredentials:
type: oauth2
description: OAuth2 Client Credentials flow. See https://developer.quinyx.com/api/authentication
flows:
clientCredentials:
tokenUrl: /oauth/v3/token
scopes: {}
schedule_OAuth2ClientCredentials:
type: oauth2
description: OAuth2 Client Credentials flow. See https://developer.quinyx.com/api/authentication
flows:
clientCredentials:
tokenUrl: /oauth/v3/token
scopes: {}
statistics_OAuth2ClientCredentials:
type: oauth2
description: OAuth2 Client Credentials flow. See https://developer.quinyx.com/api/authentication
flows:
clientCredentials:
tokenUrl: /oauth/v3/token
scopes: {}