OneTrust Magic Link Tokens V4 API

openapi: 3.2.0
info:
  title: Consent & Preferences - Universal Consent & Preference…
  version: '1.0'
  contact:
    name: OneTrust Support
    url: https://my.onetrust.com/s/contactsupport
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  description: The Universal Consent & Preference Management APIs are used to integrate external systems and streamline the flow of data with Universal Consent & Preference Management in the OneTrust Platform.
servers:
- url: https://{hostname}
  variables:
    hostname:
      default: hostname
      description: The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com.
tags:
- name: Magic Link Tokens V4
  description: The Magic Link Tokens V4 APIs are used to manage secure, time-limited tokens for data subject verification and authentication.
  externalDocs:
    description: OpenAPI 3.1.0 - Download Definition
    url: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
  x-displayName: Magic Link Tokens V4
paths:
  /rest/api/consent/v4/datasubjects/linktokens:
    get:
      operationId: getEmailLinkTokenByDataSubjectV4
      summary: Get Data Subject Token
      description: Use this API to retrieve the link token for a specific data subject.
      tags:
      - Magic Link Tokens V4
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: identifier
        in: header
        description: The data subject identifier of the data subject.
        required: true
        schema:
          type: string
        example: example@otprivacy.com
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentAPI_EmailLinkTokenResponseDto'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: string
        '429':
          description: "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview)."
          headers:
            Retry-After:
              schema:
                description: The number of seconds after which requests will be allowed again.
                format: int32
            ot-period:
              schema:
                description: The unit of time for which the rate limit applies
                enum:
                - HOUR
                - MINUTE
            ot-ratelimit-event-id:
              schema:
                description: The unique identifier for the rate-limiting event.
                format: uuid
            ot-request-made:
              schema:
                description: The number of requests made within the specified period.
                format: int32
            ot-requests-allowed:
              schema:
                description: The number of requests allowed within the specified period.
                format: int32
        '500':
          description: Internal Server Error
      security:
      - ConsentAPI_OAUTH2:
        - CONSENT
  /rest/api/consent/v4/linktokens:
    get:
      operationId: getEmailLinkTokensListV4
      summary: Get List of Data Subject Tokens
      description: 'Use this API to retrieve a list of link tokens created between a specified date range for all data subjects.


        > 🗒 Things to Know

        >

        > - The maximum date range that can be returned is 7 days.'
      tags:
      - Magic Link Tokens V4
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: fromDate
        in: query
        description: The start of a date and time range used to filter results.
        required: true
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00'
      - name: toDate
        in: query
        description: The end of a date and time range used to filter results.
        required: true
        schema:
          type: string
          format: date-time
        example: '2024-01-07T23:59:59'
      - name: requestContinuation
        in: header
        description: The token used to paginate a response if the number of records is more than a page.
        required: false
        schema:
          type: string
        example: '{\"compositeToken\": \"jmxpAKZxe9nZkAoAAAAAAA==\"}'
      - name: page
        in: query
        description: The page number of the results.
        schema:
          type: integer
          default: 0
          minimum: 0
        example: 0
      - name: size
        in: query
        description: The number of results per page.
        schema:
          type: integer
          default: 20
          maximum: 50
          minimum: 1
        example: 20
      - name: sort
        in: query
        description: The sort criteria that dictates the order of the results.
        schema:
          type: string
          default: expiryDate,asc
          enum:
          - expiryDate,asc
          - expiryDate,desc
        example: expiryDate,desc
      responses:
        '200':
          description: 'OK


            List of Email Link Tokens retrieved successfully.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentAPI_EmailLinkTokenSliceDto'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: string
        '429':
          description: "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview)."
          headers:
            Retry-After:
              schema:
                description: The number of seconds after which requests will be allowed again.
                format: int32
            ot-period:
              schema:
                description: The unit of time for which the rate limit applies
                enum:
                - HOUR
                - MINUTE
            ot-ratelimit-event-id:
              schema:
                description: The unique identifier for the rate-limiting event.
                format: uuid
            ot-request-made:
              schema:
                description: The number of requests made within the specified period.
                format: int32
            ot-requests-allowed:
              schema:
                description: The number of requests allowed within the specified period.
                format: int32
        '500':
          description: Internal Server Error
      security:
      - ConsentAPI_OAUTH2:
        - CONSENT
components:
  schemas:
    ConsentAPI_EmailLinkTokenResponseDto:
      type: object
      properties:
        token:
          description: The data subject link token. This token can be appended to the preference center URL to form the preference center magic link.
          type: string
          example: QFpXYCFOYUrFZfstplM5l1hjdLv4YlaQtkbYt7gpZUc=
        identifier:
          description: The data subject identifier of the data subject.
          type: string
          example: example@otprivacy.com
        createdDate:
          description: The date and time that the data subject link token was created.
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000'
        expiryDate:
          description: The date and time that the data subject link token expires.
          type: string
          format: date-time
          example: '2024-02-01T00:00:00.000'
    ConsentAPI_EmailLinkTokenSliceDto:
      type: object
      properties:
        content:
          items:
            $ref: '#/components/schemas/ConsentAPI_EmailLinkTokenResponseDto'
          type: array
        number:
          description: The page number of the results.
          type: integer
          format: int32
          example: 1
        size:
          description: The number of results per page.
          type: integer
          format: int32
          example: 20
        pageable:
          $ref: '#/components/schemas/ConsentAPI_PageableObject'
        last:
          description: Flag indicating whether this is the last page or not.
          type: boolean
          example: false
        sort:
          $ref: '#/components/schemas/ConsentAPI_SortObject'
        first:
          type: boolean
        numberOfElements:
          type: integer
          format: int32
        empty:
          type: boolean
        requestContinuation:
          description: The token used to paginate a response if the number of records is more than a page.
          type: string
          example: '{\"compositeToken\": \"jmxpAKZxe9nZkAoAAAAAAA==\"}'
    ConsentAPI_PageableObject:
      type: object
      properties:
        offset:
          type: integer
          format: int64
        sort:
          $ref: '#/components/schemas/ConsentAPI_SortObject'
        pageNumber:
          type: integer
          format: int32
        paged:
          type: boolean
        pageSize:
          type: integer
          format: int32
        unpaged:
          type: boolean
    ConsentAPI_SortObject:
      type: object
      properties:
        empty:
          type: boolean
        sorted:
          type: boolean
        unsorted:
          type: boolean
  securitySchemes:
    ConsentPreferences-UniversalConsentPreferenceManag_OAUTH2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{hostname}/api/access/v1/oauth/token
          scopes:
            CONSENT: Consent Scope gives the user access to read/write operations
            CONSENT_READ: Consent Read Scope gives the user read-only access
    ConsentAPI_OAUTH2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{hostname}/api/access/v1/oauth/token
          scopes:
            CONSENT: Consent Scope gives the user access to read/write operations
            CONSENT_READ: Consent Read Scope gives the user read-only access
    DSPreferneceCache_OAUTH2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{hostname}/api/access/v1/oauth/token
          scopes:
            CONSENT: Consent Scope gives the user access to read/write operations
            CONSENT_READ: Consent Read Scope gives the user read-only access
x-readme:
  explorer-enabled: false
  proxy-enabled: false
  metrics-enabled: false
x-onetrust:
  spec-label: OpenAPI 3.1.0