PartsTech Auth API

openapi: 3.2.0
info:
  version: 2.021.1
  title: PartsTech Auth API
  description: "\n# Rate Limiting\n\nRequests can be limited by user requests, by private partner requests and by all requests with partner's credentials.\nIt has several time intervals:\n  - *Per day* restricts count of requests made in one day.\n  - *Requests per second* restricts count of requests made in one second.\n  - *Concurrent requests* restricts count of parallel requests.\n  - *Sliding 15 minutes* restricts count of requests made in last 15 minutes.\n\n**Note**: Every method has own separate sets of the limits.\n\n## Headers\nUse the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.\nThe HTTP header is returned only for one general limit or for limit that user reached.\n\n\n*Headers*\n  - the rate limit ceiling for that given endpoint:\n  ```\n  x-rate-limit-limit: 1000\n  ```\n  - the number of requests left:\n  ```\n  x-rate-limit-remaining: 570\n  ```\n  - the remaining window before the rate limit resets, in UTC [epoch seconds](https://en.wikipedia.org/wiki/Unix_time):\n  ```\n  x-rate-limit-reset: 1552003200\n  ```\n\nWhen an application exceeds the rate limit for a given standard API endpoint,\nthe API will return a HTTP 429 “Too Many Requests” response code, and the following error will be returned in the response body:\n```\n{\n  \"error\": {\n    \"code\": \"TooManyRequests\",\n    \"message\": \"Some description\"\n  }\n}\n```\n\n# Pagination\n\nWhen you call an API method to retrieve information, it can be returned to you in portions.\nCheck out more detail below on pagination in API methods, including how to use them and which methods follow the pattern.\n\nAPI methods that supports pagination will return the `Link` header. It will include available urls of `first`, `last`, `previous` and `next` pages.\n\n```\nLink: <https://api.partstech.com/purchases?page=1>; rel=\"first\"\nLink: <https://api.partstech.com/purchases?page=1>; rel=\"previous\"\nLink: <https://api.partstech.com/purchases?page=3>; rel=\"next\"\nLink: <https://api.partstech.com/purchases?page=142>; rel=\"last\"\n```\n\n# MOTOR Compliance Requirements\n\nAll MOTOR-powered endpoints (Labor, Maintenance Schedules, Fluids, and Specifications) return a `Link` header\ncontaining the URL to MOTOR's OEM Compliance Requirements documentation.\n\nThe header follows the [RFC 8288 (Web Linking)](https://tools.ietf.org/html/rfc8288) format:\n\n```\nLink: <https://www.motor.com/oem-compliance-requirements/>; rel=\"compliance\"\n```\n\n# Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:\n\n```\n{\n  \"error\": {\n    \"code\": \"InternalErrorCode\",\n    \"message\": \"Some description\"\n  }\n}\n```\n\n# Error Responses\nSome default error responses used in the API.\n\nHttp Code  | Explanation | Content Type | Used error codes\n----------------|-------------|------------------|---------\n400 | Bad Request. The request was unacceptable. | `application/json` | `InvalidRequestSyntax`\n401 | Unauthorized. The request requires user or partner credentials or bearer token. Also used for invalid credentials or bearer token. | `application/json` | `InvalidToken`, `UserAuthenticationFailed`, `PartnerAuthenticationFailed`\n402 | Request Failed. The parameters were valid but the request failed. | `application/json` | Different codes, depend on method.\n403 | Forbidden. Also used for unauthorized requests such as improper credentials scopes or permissions issues. | `application/json` | `IncorrectMode`, `DisabledApiUsage`, `UserIsNotActivated`, `HaveNotPermission`, `NotAvailableMethod`\n404 | Some data in the request is not found. Or incorrect url was used. | `application/json`, `text/html`, no content | `NotFound`\n405 | Method not allowed. | `application/json`, `text/html`, no content |\n406 | Unacceptable content type. Client sent an accepts header for a content type which does not exist on the server. | No content |\n409 | Locked. One of the another operations that is in progress blocks this method call. | `application/json` | `LockedSession`\n429 | Too Many Requests | `application/json` | `TooManyRequests`\n432 | Integration Error | `application/json` |\n500 | Internal Server Error. (This is rare.) | `application/json` | `InternalError`\n501 | Not Implemented | `application/json` | `MethodNotImplemented`\n503 | The backend server is not available. (This is rare.) | No content |\n"
  x-logo:
    url: https://partstech.com/wp-content/uploads/2025/03/PartsTech_OEC-compnay_logo.svg
    altText: PartsTech logo
servers:
- url: https://api.partstech.com
  description: Production server
- url: https://api.beta.partstech.com
  description: Beta server
tags:
- name: auth
  description: 'A valid JSON Web Token (JWT) is required to access API methods. A JWT access token must be included in the authorization header of each request in the following Bearer schema:

    ```

    Authorization: Bearer <accessToken>

    ```

    Use the Get Access method to get a valid access token. Each access token expires after 60 minutes.

    '
  x-displayName: Authentication and Access
paths:
  /oauth/access:
    post:
      summary: Get Access
      description: "Generates and returns a valid access token to use in request headers for access to methods.\n\nEach method requires either `user` or `partner` access type for authorization. The required access type for a given method can be viewed in the Authorizations section of each method's documentation.\n - To get a valid `accessToken` for methods that require `user` access type, provide `UserCredentials` and the value `user` for `accessType` in the request. For punchout integrations, all Punchout and Cart methods require `user` access type.\n - To get a valid `accessToken` for methods that require `partner` access type, provide `PartnerCredentials` and the value `partner` for `accessType` in the request.\n\nCheck out the Request Body Schema below to view what user and partner information is required in the `UserCredentials` and `PartnerCredentials` objects.\n\nThe response contains a valid `accessToken` that must be included in the authorization header of requests to access other methods. The authorization header format is ```Authorization: Bearer <accessToken>```\n"
      operationId: getAcessToken
      x-operation-name: CreateAccessToken
      tags:
      - auth
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - credentials
              - accessType
              properties:
                accessType:
                  type: string
                  description: Specify an access type for method authorization
                  enum:
                  - user
                  - partner
                credentials:
                  oneOf:
                  - $ref: '#/components/schemas/UserCredentials'
                  - $ref: '#/components/schemas/PartnerCredentials'
      responses:
        '200':
          $ref: '#/components/responses/Tokens'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/AuthenticationFailed'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '406':
          description: Unacceptable content type. Client sent an accepts header for a content type which does not exist on the server.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: The backend server is not available.
  /oauth/refresh:
    post:
      summary: Refresh Access
      deprecated: true
      description: 'Refresh an access token.

        A response is the same to [`/oauth/access`](#operation/getAcessToken)

        '
      operationId: refreshAccessToken
      x-operation-name: RefreshAccessToken
      tags:
      - auth
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - refreshToken
              properties:
                refreshToken:
                  type: string
                  description: A JWT token received in the Access request
                  example: Some JWT token
      responses:
        '200':
          $ref: '#/components/responses/Tokens'
        '401':
          $ref: '#/components/responses/InvalidToken'
components:
  responses:
    InternalServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                $ref: '#/components/schemas/Error'
            example:
              error:
                code: InternalError
                message: Internal error
    InvalidRequest:
      description: Malformed request. The request body is not parse-able or with invalid content.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvalidRequestError'
    ForbiddenError:
      description: Forbidden. Also used for unauthorized requests such as improper credentials scopes or permissions issues.
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                title: Error details
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                  message:
                    type: string
          examples:
            NotAvailableMethod:
              value:
                error:
                  code: NotAvailableMethod
                  message: Method is not available
            HaveNotPermission:
              value:
                error:
                  code: HaveNotPermission
                  message: Invalid credentials were provided
            UserIsNotActivated:
              value:
                error:
                  code: UserIsNotActivated
                  message: User is not activated. Please verify your email by clicking a link in the email from PartsTech that was sent to you.
            DisabledApiUsage:
              value:
                error:
                  code: DisabledApiUsage
                  message: User did not approve api usage or disable it
            IncorrectMode:
              value:
                error:
                  code: IncorrectMode
                  message: Incorrect user for test mode
    Tokens:
      description: OK
      content:
        application/json:
          schema:
            type: object
            required:
            - tokenType
            - accessToken
            - expiresIn
            - partner
            properties:
              tokenType:
                type: string
                enum:
                - bearer
              accessToken:
                type: string
                description: A valid JSON Web Token
                example: some JWT token
              refreshToken:
                type:
                - string
                - 'null'
                deprecated: true
                example: some JWT token
              expiresIn:
                type: integer
                format: int64
                description: Time until `accessToken` expires, 60 minutes.
                example: 10947234663
              username:
                type: string
                description: The Username/UserId of the user provided in the request. Present when `user` access type is requested.
                example: partstech_user
              partner:
                type: string
                description: The Partner Id of the partner provided in the request.
                example: partstech_partner
    InvalidToken:
      description: Invalid Token.
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                title: Error details
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - InvalidToken
                    - ExpiredToken
                  message:
                    type: string
            example:
              error:
                code: InvalidToken
                message: Invalid token was provided
    AuthenticationFailed:
      description: Unauthorized. The request requires user or partner credentials or bearer token. Also used for invalid credentials or bearer token.
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                title: Error details
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                  message:
                    type: string
          examples:
            ExpiredToken:
              value:
                error:
                  code: InvalidToken
                  message: Provided token is expired
            InvalidToken:
              value:
                error:
                  code: InvalidToken
                  message: Provided token is invalid
            UserAuthenticationFailed:
              value:
                error:
                  code: UserAuthenticationFailed
                  message: Incorrect user id or user key
            PartnerAuthenticationFailed:
              value:
                error:
                  code: PartnerAuthenticationFailed
                  message: Incorrect partner id or partner key
  schemas:
    Error:
      title: Error Definition
      type: object
      required:
      - code
      - message
      properties:
        code:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
    UserCredentials:
      type: object
      description: User And Partner Auth Credentials
      required:
      - user
      - partner
      properties:
        user:
          $ref: '#/components/schemas/IdentityKey'
        partner:
          $ref: '#/components/schemas/IdentityKey'
      example:
        user:
          id: partstech_user
          key: User API key
        partner:
          id: partstech_partner
          key: Partner API key
    InvalidRequestError:
      description: Malformed request. The request body is not parse-able or with invalid content.
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
        validationErrors:
          type: array
          items:
            type: string
      example:
        error:
          code: InvalidRequestSyntax
          message: Cannot parse request. Invalid data format
        validationErrors:
        - credentials.user.key - This value should not be blank.
        - credentials.user.id - This value should be of type string.
        - credentials.partner - This value should not be blank.
    PartnerCredentials:
      type: object
      description: Partner Auth Credentials
      required:
      - partner
      properties:
        partner:
          $ref: '#/components/schemas/IdentityKey'
      example:
        partner:
          id: partstech_partner
          key: Partner API key
    IdentityKey:
      type: object
      description: User or Partner ID and API Key
      required:
      - id
      - key
      properties:
        id:
          type: string
          description: User or Partner ID
          example: username
        key:
          type: string
          description: User or Partner API key
          example: APIkey
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Get access to data while protecting your account credentials.\nToken (a JWT token) are also a safer and more secure way to give you access.\n\nIt provides two ways of access:\n - `user` - Give an access to user methods.\n - `partner` - Give an acess to partner methods.\n\nTo use this way you need:\n1. Get an access token. See [\"Authentication and Access\"](#operation/getAcessToken).\n2. Add a header in the request\n```\nAuthorization: Bearer <accessToken>\n```\n3. Refresh tokens, when it expires, using `refreshToken`. See [\"Authentication and Access\"](#operation/refreshAccessToken). **Deprecated**.\nGenerate a new token after an expiration of previous instead of refreshing .\n"
    apiKeyAuth:
      type: apiKey
      in: header
      name: credentials
      description: "It is a deprecated way to get access to the methods, used only in the methods, that were in the previous version.\n\nIt provides two ways of an access:\n - `user` - Give access to user methods.\n - `partner` - Give acess to partner methods.\n\nTo use this way you need to add credentials in the request body, where it is allowed, in a next format:\n - for user methods:\n```\n\"credentials\": {\n    \"user\": {\n      \"id\": \"username\",\n      \"key\": \"APIKey\"\n    },\n    \"partner\": {\n      \"id\": \"username\",\n      \"key\": \"APIKey\"\n    }\n}\n```\n - for partner methods:\n```\n\"credentials\": {\n    \"partner\": {\n      \"id\": \"username\",\n      \"key\": \"APIKey\"\n    }\n}\n```\n\nFor example content of method [`Submit Cart`](#operation/submitCart) will be modified:\n```\n{\n  \"sessionId\": \"123asjkdhyr34234\"\n}\n```\n\n```\n{\n  \"sessionId\": \"123asjkdhyr34234\",\n  \"credentials\": {\n    \"user\": {\n      \"id\": \"mechanic\",\n      \"key\": \"Mechanic's API key\"\n    },\n    \"partner\": {\n      \"id\": \"partner name\",\n      \"key\": \"partner's API key\"\n    }\n  }\n}\n```\n"
x-tagGroups:
- name: Authentication
  tags:
  - auth
- name: Punchout
  tags:
  - punchout_quote
- name: Cart
  tags:
  - punchout-cart
  - session-cart
  - callback-cart
  - punchout-orders
  - custom-cart
- name: Catalog
  tags:
  - vin
  - search
  - quoting
  - parts
  - tires
  - brands
- name: Taxonomy
  tags:
  - pcdb
  - vcdb
  - jobs
- name: Profile
  tags:
  - user
  - shop
  - supplier_preferences
  - orders
- name: Partner
  tags:
  - users
  - shops
  - ex-permissions
  - partner-orders
  - auto-connect
- name: Others
  tags:
  - suppliers
  - local-inventory
- name: Motor Taxonomy
  tags:
  - motor-labor
  - motor-maintenance-schedules
  - motor-fluids
  - motor-specifications
- name: Mitchell1 Taxonomy
  tags:
  - mitchell1
  - mitchell1-labor