Clockodo Access Group Access API

openapi: 3.2.0
info:
  title: Clockodo API Documentation Access Group Access API
  description: '# Clockodo REST API


    Our API opens Clockodo for other systems. Billing and project management applications or custom shell scripts, for example, are useful mash-ups with Clockodo. As a REST API, the interface allows you to query and modify Clockodo data and control the clock via HTTP in JSON format. ## URL of the Clockodo API


    You can access our API via the following URL:


    ```text

    https://my.clockodo.com/api/[resource type]

    ```


    The resource type represents a class of your data. Once you request a specific resource, for example, query information about exactly one entity, you can use the following URL:


    ```text

    https://my.clockodo.com/api/[resource type]/[resource ID]

    ```


    In the following sections of this documentation, you will find more detailed descriptions of the available endpoints for each resource type. For example, under Entry you will find detailed information on how you can manage time entries in your Clockodo environment. ## HTTP Verbs


    To tell the API which operations you want to perform on the resources, the so-called verbs of the HTTP protocol are used. The following operations are usually possible:


    | HTTP Verb | Description |

    |-----------------------------|-----------------------------------------------------------------|

    | `GET` | Query a list of all the resources of the selected resource type |

    | `GET` (with resource ID) | Query exactly one resource |

    | `POST` | Create a new resource |

    | `PUT` (with resource ID) | Update or edit a resource |

    | `DELETE` (with resource ID) | Delete a resource |


    ## Authentication


    Clockodo supports two authentication approaches:


    - **API key authentication**, using a Clockodo user''s email address and personal API key. The credentials can be sent either via HTTP Basic authentication or via Clockodo-specific HTTP headers. - **OAuth 2.0**, using delegated access with scoped bearer tokens. ### API key authentication


    Each Clockodo user has personal API access that takes the user''s access rights into account. You can find your API key under the menu item "Personal data" in your Clockodo account. Changing your Clockodo password invalidates your existing API key. If you use the API key for an integration, you must update the integration with the new API key after changing your password. #### HTTP Basic authentication


    To access your data via the API, authenticate using your email address and API key with the basic authentication mechanism of the HTTP protocol:


    ```text

    User: [email address]

    Password: [API key]

    ```


    Basic authentication is transmitted in the `Authorization` HTTP header. Most HTTP clients generate this header automatically from the credentials above:


    ```http

    Authorization: Basic

    ```


    **Example:** For the user `admin@clockodo.com` with the API key `nl9tzwlwr4kzmd1qcbmtli60jpwd2c9g`, the header is:


    ```http

    Authorization: Basic YWRtaW5AY2xvY2tvZG8uY29tOm5sOXR6d2x3cjRrem1kMXFjYm10bGk2MGpwd2QyYzln

    ```


    #### Clockodo API headers


    Alternatively, you can send the same credentials using Clockodo-specific HTTP headers:


    ```http

    X-ClockodoApiUser: [email address]

    X-ClockodoApiKey: [API key]

    ```


    #### Client identification


    Requests using either of the API-key authentication methods described above must also identify the calling application and provide the email address of a technical contact person. For this purpose, include the following HTTP header with every request:


    ```http

    X-Clockodo-External-Application: [name of application or company];[email address]

    ```


    **Example:**


    ```http

    X-Clockodo-External-Application: Clockodo;admin@clockodo.com

    ```


    This header is not required for requests authenticated with an OAuth bearer token. ### OAuth 2.0


    Clockodo supports OAuth 2.0 for integrations that use delegated access with scoped bearer tokens. It is accepted across the whole API as an alternative to API key authentication. Every access token is tied to a Clockodo user and is subject to that user''s access rights, just like an API key.'
  termsOfService: https://www.clockodo.com/en/terms-and-conditions/
  contact:
    name: Clockodo support
    url: https://www.clockodo.com/en/about-us/
    email: support@clockodo.com
  version: '2026-10-16'
  x-logo:
    url: /clockodo-logo.svg
    href: /
    altText: Clockodo Logo
    backgroundColor: '#3d2a5a'
servers:
- url: https://my.clockodo.com/api
security:
- BasicAuth: []
  ExternalApp: []
- User: []
  Key: []
  ExternalApp: []
- OAuth2: []
tags:
- name: AccessGroupAccess
  description: Manage access group rights
paths:
  /v2/accessGroups/{accessGroupsId}/customers:
    put:
      tags:
      - AccessGroupAccess
      operationId: updateAccessGroupCustomersByIdV2
      parameters:
      - name: accessGroupsId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - id
              - type
              - value
              properties:
                id:
                  type: integer
                  minimum: 1
                type:
                  $ref: '#/components/schemas/AccessType'
                value:
                  $ref: '#/components/schemas/AccessValue'
              type: object
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer_projects_access_v2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
      deprecated: false
      summary: Update access group customers by id V2
      x-summary-source: derived
  /v2/accessGroups/{accessGroupsId}/customers/general:
    put:
      tags:
      - AccessGroupAccess
      operationId: updateAccessGroupCustomersGeneralByIdV2
      parameters:
      - name: accessGroupsId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - type
              - value
              properties:
                type:
                  $ref: '#/components/schemas/AccessType'
                value:
                  $ref: '#/components/schemas/AccessValue'
              type: object
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer_projects_access_v2'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiAccessGroupsCustomersGeneralV2Errors'
                type: object
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
      deprecated: false
      summary: Update access group customers general by id V2
      x-summary-source: derived
  /v2/accessGroups/{accessGroupsId}/customersProjects:
    get:
      tags:
      - AccessGroupAccess
      operationId: getAccessGroupCustomersProjectsByIdV2
      parameters:
      - name: accessGroupsId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer_projects_access_v2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
      deprecated: false
      summary: Get access group customers projects by id V2
      x-summary-source: derived
  /v2/accessGroups/{accessGroupsId}/projects:
    put:
      tags:
      - AccessGroupAccess
      operationId: updateAccessGroupProjectsByIdV2
      parameters:
      - name: accessGroupsId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - id
              - type
              - value
              properties:
                id:
                  type: integer
                  minimum: 1
                type:
                  $ref: '#/components/schemas/AccessType'
                value:
                  $ref: '#/components/schemas/ApiAccessGroupsProjectsV2_AccessValueForPut'
              type: object
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer_projects_access_v2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
      deprecated: false
      summary: Update access group projects by id V2
      x-summary-source: derived
  /v2/accessGroups/{accessGroupsId}/services:
    get:
      tags:
      - AccessGroupAccess
      operationId: getAccessGroupServicesByIdV2
      parameters:
      - name: accessGroupsId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/services_access_v2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
      deprecated: false
      summary: Get access group services by id V2
      x-summary-source: derived
    put:
      tags:
      - AccessGroupAccess
      operationId: updateAccessGroupServicesByIdV2
      parameters:
      - name: accessGroupsId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - id
              - type
              - value
              properties:
                id:
                  type: integer
                  minimum: 1
                type:
                  $ref: '#/components/schemas/ApiAccessGroupsServicesV2_AccessTypeForPut'
                value:
                  $ref: '#/components/schemas/ApiAccessGroupsServicesV2_AccessValueForPut'
              type: object
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/services_access_v2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
      deprecated: false
      summary: Update access group services by id V2
      x-summary-source: derived
  /v2/accessGroups/{accessGroupsId}/services/general:
    put:
      tags:
      - AccessGroupAccess
      operationId: updateAccessGroupServicesGeneralByIdV2
      parameters:
      - name: accessGroupsId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          examples:
          - 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - type
              - value
              properties:
                type:
                  $ref: '#/components/schemas/ApiAccessGroupsServicesGeneralV2_AccessTypeForPut'
                value:
                  $ref: '#/components/schemas/AccessValue'
              type: object
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/services_access_v2'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiAccessGroupsServicesGeneralV2Errors'
                type: object
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralErrors'
      deprecated: false
      summary: Update access group services general by id V2
      x-summary-source: derived
components:
  schemas:
    ApiErrors:
      properties:
        type:
          description: Unique identifier of the error
          type: string
          examples:
          - General
        message:
          description: Textual error description
          type: string
          examples:
          - The requested resource could not be found.
        details:
          description: Additional error details if necessary
          type:
          - object
          - 'null'
          examples:
          - null
        path:
          type:
          - string
          - 'null'
      type: object
    customer_projects_access_v2:
      required:
      - add
      - report
      - edit
      properties:
        add:
          oneOf:
          - $ref: '#/components/schemas/general_access_v2'
          - $ref: '#/components/schemas/custom_access_v2'
          examples:
          - true
        report:
          oneOf:
          - $ref: '#/components/schemas/general_access_v2'
          - $ref: '#/components/schemas/custom_access_v2'
          examples:
          - '123': true
            '456': true
        edit:
          oneOf:
          - $ref: '#/components/schemas/general_access_v2'
          - $ref: '#/components/schemas/custom_access_v2'
          examples:
          - '123': true
            '456':
              projects:
                '789': true
      type: object
    ApiAccessGroupsServicesV2_AccessTypeForPut:
      title: Access type for put
      description: 'Possible values:

        - `add`: AddData'
      type: string
      enum:
      - add
      x-enumNames:
      - AddData
    BlockingAccessDependenciesError:
      title: Blocking access dependencies error
      properties:
        type:
          type: string
          enum:
          - BlockingAccessDependencies
        message:
          type:
          - string
          - 'null'
          examples:
          - Blocking dependencies need to be removed beforehand.
        path:
          type:
          - string
          - 'null'
        details:
          $ref: '#/components/schemas/BlockingAccessDependencies'
      type: object
      x-error-category: Forbidden
    services_access_v2:
      required:
      - add
      properties:
        add:
          oneOf:
          - $ref: '#/components/schemas/general_access_v2'
          - description: Access to selected services
            type: object
            additionalProperties:
              description: Key value pairs in the format {service id} => true
              type: boolean
              enum:
              - true
          examples:
          - '123': true
            '456': true
      type: object
    custom_access_v2:
      description: Access only to selected customers
      type: object
      additionalProperties:
        description: Key value pairs in the format {customer id} => true or {customer id} => {} for selected projects
        oneOf:
        - description: Access to selected customers
          type: boolean
          enum:
          - true
        - description: Access to selected projects
          required:
          - projects
          properties:
            projects:
              type: object
              additionalProperties:
                description: Key value pairs in the format {project id} => true
                type: boolean
                enum:
                - true
          type: object
    ApiAccessGroupsServicesV2_AccessValueForPut:
      title: Access value for put
      description: 'Possible values:

        - `0`: NoAccess

        - `1`: FullAccess'
      type: integer
      enum:
      - 0
      - 1
      x-enumNames:
      - NoAccess
      - FullAccess
    ApiAccessGroupsServicesGeneralV2_AccessTypeForPut:
      title: Access type for put
      description: 'Possible values:

        - `add`: AddData'
      type: string
      enum:
      - add
      x-enumNames:
      - AddData
    BlockingAccessDependencies:
      title: There are blocking access dependencies that need to be removed beforehand
      required:
      - access_name
      properties:
        access_name:
          description: The access you were trying to remove
          type: string
          examples:
          - see_absences
        elevated_access_dependencies:
          description: Elevated access dependencies that are blocking
          type: array
          items:
            type: string
          examples:
          - - see_work_time
            - manage_work_time
      type: object
    AccessValue:
      title: Access value
      description: 'Possible values:

        - `0`: NoAccess

        - `1`: FullAccess

        - `2`: CustomAccess'
      type: integer
      enum:
      - 0
      - 1
      - 2
      x-enumNames:
      - NoAccess
      - FullAccess
      - CustomAccess
    ApiAccessGroupsProjectsV2_AccessValueForPut:
      title: Access value for put
      description: 'Possible values:

        - `0`: NoAccess

        - `1`: FullAccess'
      type: integer
      enum:
      - 0
      - 1
      x-enumNames:
      - NoAccess
      - FullAccess
    ApiAccessGroupsCustomersGeneralV2Errors:
      title: Api access groups customers general v2 errors
      required:
      - error
      properties:
        error:
          title: Errors
          type: object
          anyOf:
          - $ref: '#/components/schemas/ForbiddenChangeToCustomAccessError'
          - $ref: '#/components/schemas/BlockingAccessDependenciesError'
      type: object
    GeneralErrors:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrors'
      type: object
    ForbiddenChangeToCustomAccessError:
      title: Forbidden change to custom access error
      properties:
        type:
          type: string
          enum:
          - ForbiddenChangeToCustomAccess
        message:
          type:
          - string
          - 'null'
          examples:
          - Change to selected access is only possible from yes.
        path:
          type:
          - string
          - 'null'
        details:
          type: 'null'
      type: object
      x-error-category: Forbidden
    general_access_v2:
      description: General access
      type: boolean
    ApiAccessGroupsServicesGeneralV2Errors:
      title: Api access groups services general v2 errors
      required:
      - error
      properties:
        error:
          title: Errors
          type: object
          anyOf:
          - $ref: '#/components/schemas/ForbiddenChangeToCustomAccessError'
      type: object
    AccessType:
      title: Access type
      description: 'Possible values:

        - `add`: AddData

        - `report`: SeeReports

        - `edit`: EditReports'
      type: string
      enum:
      - add
      - report
      - edit
      x-enumNames:
      - AddData
      - SeeReports
      - EditReports
  securitySchemes:
    BasicAuth:
      type: http
      description: The basic authentication of the HTTP protocol. Credentials are email address and API key.<br />Every co-worker will find his API key in the menu item "Personal data" in his Clockodo account.
      scheme: basic
    User:
      type: apiKey
      description: 'Must be filled together with <code>X-ClockodoApiKey</code><br /><strong>Example: admin@clockodo.com</strong>'
      name: X-ClockodoApiUser
      in: header
    Key:
      type: apiKey
      description: Must be filled together with <code>X-ClockodoApiUser</code>
      name: X-ClockodoApiKey
      in: header
    ExternalApp:
      type: apiKey
      description: 'Every request to our API must provide identification of the calling application, including the email address of a technical contact person.<br /><strong>Example: "Clockodo;admin@clockodo.com"</strong>'
      name: X-Clockodo-External-Application
      in: header
    OAuth2:
      type: oauth2
      description: OAuth 2.0 for external integrations via authorization code flow with refresh tokens. OAuth clients can be provisioned via Dynamic Client Registration (POST /oauth/register) or Client ID Metadata Documents (CIMD). Dynamically registered clients are deleted after 90 days without any token or authorization code activity; store the issued client_id and client_secret permanently, as the secret is only returned once.
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /token
          refreshUrl: /token
          scopes:
            full_access: Full access to all API endpoints
            accessGroups:read: Read access group data
            accessGroups:write: Write access group data
            absences:read: Read absence data
            absences:write: Write absence data
            browserExtensionRules:read: Read browser extension rule data
            browserExtensionRules:write: Write browser extension rule data
            clock:read: Read clock data
            clock:write: Write clock data
            company:read: Read company data
            customers:read: Read customer data
            customers:write: Write customer data
            entryGroups:read: Read entry group data
            entryGroups:write: Write entry group data
            entries:read: Read time entry data
            entries:write: Write time entry data
            entriesTexts:read: Read time entry text data
            entriesTexts:write: Write time entry text data
            holidaysCarry:read: Read holiday carryover data
            holidaysCarry:write: Write holiday carryover data
            holidaysQuota:read: Read holiday quota data
            holidaysQuota:write: Write holiday quota data
            lumpSumServices:read: Read lump sum service data
            lumpSumServices:write: Write lump sum service data
            nonbusinessDays:read: Read nonbusiness day data
            nonbusinessDays:write: Write nonbusiness day data
            nonbusinessGroups:read: Read nonbusiness group data
            nonbusinessGroups:write: Write nonbusiness group data
            overtimeCarry:read: Read overtime carryover data
            overtimeCarry:write: Write overtime carryover data
            overtimeReductions:read: Read overtime reduction data
            overtimeReductions:write: Write overtime reduction data
            projects:read: Read project data
            projects:write: Write project data
            rates:read: Read rate data
            rates:write: Write rate data
            services:read: Read service data
            services:write: Write service data
            subprojects:read: Read subproject data
            subprojects:write: Write subproject data
            subscription:read: Read subscription data
            targetHours:read: Read planned hours data
            targetHours:write: Write planned hours data
            teams:read: Read team data
            teams:write: Write team data
            userReports:read: Read co-worker report data
            users:read: Read co-worker data
            users:write: Write co-worker data
            usersNonbusinessDays:read: Read co-worker nonbusiness day data
            usersNonbusinessGroups:read: Read co-worker nonbusiness group data
            usersNonbusinessGroups:write: Write co-worker nonbusiness group data
            workTimes:read: Read work time data
            workTimes:write: Write work time data
x-provenance:
  method: harvested
  publisher: Clockodo
  source: https://docs.clockodo.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)