Talon.One Roles API

openapi: 3.2.0
info:
  title: Management Roles API
  version: ''
  description: 'The Management API allows you to programmatically do what the Campaign Manager

    does.'
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Roles
  description: 'Represents a set of permissions assigned to a user.


    See the docs.'
paths:
  /v2/roles:
    get:
      operationId: listAllRolesV2
      summary: List roles
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        List all roles.'
      tags:
      - Roles
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - totalResultSize
                - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RoleV2'
  /v2/roles/{roleId}:
    get:
      operationId: getRoleV2
      summary: Get role
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Get the details of a specific role. To see all the roles, use the List roles endpoint.'
      tags:
      - Roles
      parameters:
      - name: roleId
        in: path
        description: 'The ID of role.


          **Note**: To find the ID of a role, use the [List roles](/management-api#tag/Roles/operation/listAllRolesV2) endpoint.

          '
        example: 9
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleV2'
    put:
      operationId: updateRoleV2
      summary: Update role
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Update a specific role.'
      tags:
      - Roles
      parameters:
      - name: roleId
        in: path
        description: 'The ID of role.


          **Note**: To find the ID of a role, use the [List roles](/management-api#tag/Roles/operation/listAllRolesV2) endpoint.

          '
        example: 9
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleV2Base'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleV2'
components:
  schemas:
    MutableEntity:
      type: object
      required:
      - modified
      properties:
        modified:
          type: string
          format: date-time
          description: The time this entity was last modified.
          example: '2021-09-12T10:12:42Z'
    RoleV2Permissions:
      type: object
      properties:
        permissionSets:
          type: array
          description: List of grouped logical operations referenced by roles.
          maxItems: 500
          items:
            $ref: '#/components/schemas/RoleV2PermissionSet'
            type: object
          example:
          - name: Application permission set
            logicalOperations:
            - getApplicationOperations
            - editApplicationOperations
          - name: Campaign manager permission set
            logicalOperations:
            - getCampaignOperations
            - createCampaignOperations
            - updateCampaignOperations
          - name: Campaign read-only permission set
            logicalOperations:
            - getCampaignOperations
          - name: Loyalty program read-only permission set
            logicalOperations:
            - getLoyaltyProgramOperations
          - name: Campaign access group manager permission set
            logicalOperations:
            - getCampaignAccessGroupOperations
            - updateCampaignAccessGroupOperations
            - deleteCampaignAccessGroupOperations
        roles:
          $ref: '#/components/schemas/RoleV2RolesGroup'
          type: object
        thresholds:
          type: array
          description: Support user limits for actions that require admin approval within the given application.
          items:
            $ref: '#/components/schemas/RolesV2Thresholds'
    RoleV2CampaignAccessGroup:
      type: object
      description: A map of the link between the campaign access group-related permission set and the Application ID the permissions apply to.
      additionalProperties:
        type: string
        description: Name of the campaign access group-related permission set.
      example:
        '5': Campaign access group manager permission set
    AccountEntity:
      type: object
      required:
      - accountId
      properties:
        accountId:
          type: integer
          description: The ID of the account that owns this entity.
          example: 3886
    RoleV2RolesGroup:
      type: object
      properties:
        applications:
          $ref: '#/components/schemas/RoleV2Application'
          type: object
        loyaltyPrograms:
          $ref: '#/components/schemas/RoleV2LoyaltyGroup'
          type: object
        campaignAccessGroups:
          $ref: '#/components/schemas/RoleV2CampaignAccessGroup'
          type: object
        account:
          type: string
          description: Name of the account-level permission set
    RoleV2Readonly:
      type: object
      properties:
        isReadonly:
          type: boolean
          example: false
          description: Identifies if the role is read-only. For read-only roles, you can only assign or unassign users. You cannot edit any other properties, such as the name, description, or permissions. The 'isReadonly' property cannot be set for new or existing roles. It is reserved for predefined roles, such as the Talon.One support role.
          default: false
    RoleV2PermissionSet:
      type: object
      required:
      - name
      - logicalOperations
      properties:
        name:
          type: string
          description: Name of the permission set.
          example: Campaign manager permission set
        logicalOperations:
          type: array
          maxItems: 1000
          description: 'List of logical operations in the permission set.

            Each logical operation must be shown under the `x-permission` tag on an endpoint level.

            '
          items:
            type: string
          example:
          - createCampaignOperations
          - getCampaignOperations
          - deleteCampaignOperations
    RolesV2Thresholds:
      type: object
      properties:
        loyaltyProgramId:
          type: integer
          description: Identifier of the loyalty program. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint.
          example: 8
        loyaltyPointsLimit:
          type: integer
          description: Maximum number of loyalty points a support user can award without approval.
          example: 100
    RoleV2:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/MutableEntity'
      - $ref: '#/components/schemas/AccountEntity'
      - $ref: '#/components/schemas/RoleV2Base'
      - $ref: '#/components/schemas/RoleV2Readonly'
    RoleV2Application:
      type: object
      description: A map of the link between the Application, campaign, or draft campaign-related permission set and the Application ID the permissions apply to.
      additionalProperties:
        $ref: '#/components/schemas/RoleV2ApplicationDetails'
        type: object
      example:
        '1':
          application: Application permission set
        '3':
          campaign: Campaign manager permission set
        '4':
          draftCampaign: Campaign read-only permission set
        '5':
          tools: Tools permission set
    RoleV2LoyaltyGroup:
      type: object
      description: A map of the link between the loyalty program-related permission set and the Application ID the permissions apply to.
      additionalProperties:
        type: string
        description: Name of the loyalty program-related permission set.
      example:
        '10': Loyalty program manager permission set
    RoleV2Base:
      type: object
      properties:
        name:
          type: string
          description: Name of the role.
          example: Campaign and campaign access group manager
        description:
          type: string
          description: Description of the role.
          example: Allows you to create and edit campaigns for specific Applications, delete specific campaign access groups, and view loyalty programs.
        permissions:
          $ref: '#/components/schemas/RoleV2Permissions'
          type: object
          description: The permissions that this role gives.
        members:
          type: array
          items:
            type: integer
          description: A list of user IDs the role is assigned to.
          example:
          - 10
          - 12
    Entity:
      type: object
      required:
      - id
      - created
      properties:
        id:
          type: integer
          description: The internal ID of this entity.
          example: 6
        created:
          type: string
          format: date-time
          description: The time this entity was created.
          example: '2020-06-10T09:05:27.993483Z'
    RoleV2ApplicationDetails:
      type: object
      properties:
        application:
          type: string
          description: Name of the Application-related permission set for the given Application.
        campaign:
          type: string
          description: Name of the campaign-related permission set for the given Application.
        draftCampaign:
          type: string
          description: Name of the draft campaign-related permission set for the given Application.
        tools:
          type: string
          description: Name of the tools-related permission set.
          example: Tools permission set
  securitySchemes:
    manager_auth:
      type: apiKey
      name: Authorization
      in: header
      description: 'This authentication scheme relies on a bearer token that you can use to

        access all the endpoints of the Management API.


        To create the token:


        1. Get a bearer token by calling the

        [createSession](#tag/Sessions/operation/createSession) endpoint.

        1. Use the `token` property of the response in the HTTP header of your

        next queries: `Authorization: Bearer $TOKEN`.


        A token is valid for 3 months. In accordance with best pratices, use

        your generated token for all your API requests. Do **not** regenerate a token for each

        request.


        > [!note]

        > We recommend that you use a [Management API key](https://docs.talon.one/management-api#section/Authentication/management_key)

        > instead of a bearer token.

        '
    management_key:
      type: apiKey
      name: Authorization
      in: header
      description: "The API key authentication gives you access to the endpoints selected by\nthe admin who created the key.\n\nUsing an API key is the recommended authentication method.\n\nThe key must be generated by an admin and given to the developer that\nrequires it:\n\n1. Sign in to the Campaign Manager and click **Account** > **Tools** >\n**Management API Keys**.\n1. Click **Create Key** and give it a name.\n1. Set an expiration date.\n   **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.\n1. Choose the endpoints the key should give access to.\n1. Click **Create Key**.\n1. Share it with your developer.\n\nThe developer can now use the API key in the HTTP header, prefixing it\nwith `ManagementKey-v1`:\n\n```\nAuthorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3\n```\n"