KeySavvy Authentication API

openapi: 3.2.0
info:
  title: KeySavvy Partner Authentication API
  version: 1.0.0
  description: API for KeySavvy Partner integration
  contact:
    name: KeySavvy API Support Team
    email: api-support@keysavvy.com
servers:
- url: https://api.keysavvy.com/v1
  description: KeySavvy Production API
- url: https://api.keysavvy.dev/v1
  description: KeySavvy Non-Production API
security:
- apiKey: []
tags:
- name: Authentication
  description: Operations related to authentication.
paths:
  /user/{referenceId}/login-link:
    post:
      tags:
      - Authentication
      summary: Send login link
      description: Sends a user an email containing a magic login link that will allow them to log in directly to the white label site. Bypasses partner site authentication.
      operationId: sendUserMagicLoginLink
      parameters:
      - name: referenceId
        in: path
        description: Reference ID of the user to send the login link to.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/CreatedResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /auth:
    post:
      tags:
      - Authentication
      summary: Authenticate user
      description: 'Authenticates a user and returns a very short-lived single-use token/url that the user

        should be redirected to in order to obtain a KeySavvy session token.


        There are two distinct ways you can choose to handle user auth:


        #### Direct

        1. Redirect the customer (either directly, or client side) to the `directRedirectUrl` value provided by this response.


        #### Cookie

        1. Include a secure, httpOnly, Set-Cookie header with a 15 second TTL in your response to

        the end-user. The cookie name and value are provided in this response as `cookieName` and `cookieValue`.


        2. Redirect the customer (either directly, or client side) to the `cookieRedirectUrl`

        value provided by this response.'
      operationId: authenticateUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequestBody'
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponseBody'
        '400':
          description: Authentication unsuccessful, see response code for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponseBody'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: 'No user exists for this `userReferenceId`. The reference ID has never been sent to `POST /user` and has never been used as a buyer or seller on a deal or vehicle. This is distinct from the `USER_NOT_ACTIVATED` 400 response, which means the user exists but has not been activated yet.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
components:
  schemas:
    ErrorResponseBody:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    AuthRequestBody:
      type: object
      properties:
        userReferenceId:
          type: string
          pattern: ^[a-zA-Z0-9_-]+$
          description: The reference ID of the user to authenticate.
        impersonatorReferenceId:
          type: string
          pattern: ^[a-zA-Z0-9_-]+$
          description: This field should uniquely identify a partner admin if they are impersonating the customer referenced in userReferenceId.
        redirectPath:
          type: string
          description: An optional post-auth redirection path. Must be a relative path starting with '/' (e.g., '/mydeals/123') and no longer than 256 characters. Invalid paths will be silently ignored and the user will be redirected to the default page.
      required:
      - userReferenceId
    CreatedResponseBody:
      type: object
      properties:
        message:
          type: string
    AuthErrorResponseBody:
      type: object
      properties:
        code:
          type: string
          enum:
          - USER_NOT_ACTIVATED
          description: "Indicates the reason this auth request failed:\n\n * `USER_NOT_ACTIVATED` - A user record exists for this reference ID, created when it was used as a buyer or seller on a deal or vehicle, but it needs to be activated with a call to `POST /user` before the user can be authed. A reference ID with no user record at all returns `404` instead.\n"
        error:
          type: string
        message:
          type: string
    AuthResponseBody:
      type: object
      properties:
        cookieValue:
          type: string
          description: The cookie value that callers should include in their response to the end user.
        cookieName:
          type: string
          description: The cookie name that callers should include in their response to the end user.
        cookieRedirectUrl:
          type: string
          format: uri
          description: An absolute URL that the end-user should be redirected to after setting the provided `cookieName` and `cookieValue`.
        directRedirectUrl:
          type: string
          format: uri
          description: An absolute URL that the end-user should be redirected to after this auth is complete. This URL does not require setting any cookies before use.
  responses:
    ErrorResponse:
      description: The request failed. `error` and `message` describe why.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    CreatedResponse:
      description: Resource created successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreatedResponseBody'
    UnauthorizedResponse:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: keysavvy-api