Talon.One Sessions API

openapi: 3.2.0
info:
  title: Management Sessions 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: Sessions
  description: 'Represents a session used for authentication purposes.

    Create one with the Create session endpoint.'
paths:
  /v1/sessions:
    post:
      operationId: createSession
      summary: Create session
      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.


        Create a session to use the Management API endpoints.


        Use the value of the `token` property provided in the response as bearer

        token in other API calls.


        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.


        This endpoint has a rate limit of 3 to 6 requests per second per account,

        depending on your setup.


        > [!note]

        > Instead of using a session, you can also use the Management API key feature

        > in the Campaign Manager to decide which endpoints can be used with a given key.'
      tags:
      - Sessions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginParams'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
    delete:
      operationId: destroySession
      summary: Destroy session
      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.


        Destroys the session.'
      tags:
      - Sessions
      responses:
        '204':
          description: No Content
components:
  schemas:
    EmailEntity:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
          example: john.doe@example.com
          description: The email address associated with the user profile.
    LoginParams:
      allOf:
      - $ref: '#/components/schemas/EmailEntity'
      - type: object
        properties:
          password:
            type: string
            description: The password for your account.
            example: admin123456
        required:
        - password
    Session:
      type: object
      properties:
        userId:
          type: integer
          description: The ID of the user of this session.
          example: 109
        token:
          type: string
          description: The token to use as a bearer token to query Management API endpoints.
          example: dy_Fa_lQ4iDAnqldJFvVEmnsN8xDTxej19l0LZDBJhQ
        created:
          type: string
          format: date-time
          description: Unix timestamp indicating when the session was first created.
          example: '2021-07-20T22:00:00Z'
      required:
      - userId
      - token
      - created
  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"