> ## Documentation Index
> Fetch the complete documentation index at: https://developer.karmacheck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate API client

> Authenticates an API client with KarmaCheck so that they can access the KarmaCheck system.



## OpenAPI

````yaml /background-check-api/api-reference/openapi.json post /auth/api
openapi: 3.1.0
info:
  title: KarmaCheck API
  description: >-
    All requests to the KarmaCheck API require a JSON Web Token (JWT) in the
    Authorization header. For an overview of the API and its authentication
    method, refer to the following topics:


    - [API basics](docs/overview/apis/api-overview.md)

    - [Authentication](docs/overview/apis/authentication.md)

    - [Environments](docs/overview/apis/environments.md)

    - [Status codes and errors](docs/overview/apis/errors.md)
  version: '1.0'
  contact:
    name: KarmaCheck
    email: customersuccess@karmacheck.com
servers:
  - description: Stage
    url: https://api-stage.karmacheck.io
  - description: Prod
    url: https://api.karmacheck.io
security:
  - JWT: []
tags:
  - name: Authentication
  - name: Cases
  - name: Candidate onboarding
  - name: Secure documents
  - name: Packages
  - name: Services
  - name: Users
  - name: Companies
  - name: Partner integrations
paths:
  /auth/api:
    post:
      tags:
        - Authentication
      summary: Authenticate API client
      description: >-
        Authenticates an API client with KarmaCheck so that they can access the
        KarmaCheck system.
      operationId: post-auth-api
      requestBody:
        content:
          application/json:
            schema:
              type: object
              x-examples:
                Example 1:
                  apiKey: 03c703eb-56cc-46f6-bb63-afb3e302d1bf
                  clientAccessToken: ffb3c8ee-412d-43e5-975a-355e3cc54cf9
              required:
                - apiKey
                - clientAccessToken
              properties:
                apiKey:
                  type: string
                  description: >-
                    A unique key that identifies the partner in the KarmaCheck
                    system. If you are building an API integration with
                    KarmaCheck, contact your Account Manager for an `apiKey`.
                    Whether you are creating an integration for your own
                    company's use, for ordering checks on behalf of mutual
                    customers of yourself and KarmaCheck, or for both, you will
                    receive one `apiKey`.
                clientAccessToken:
                  type: string
                  description: >-
                    A secret that grants an API partner access to a specific
                    group of a company. The combination of an `apiKey` and a
                    `clientAccessToken` generates a `token` for that group. If
                    you're building an integration to order checks for:

                    - **Your own company:** Contact your Account Manager to get
                    a `clientAccessToken` for each group you wish to order
                    checks for over the API.

                    - **A mutual customer:** Contact that mutual customer for
                    them to give you `clientAccessToken`s associated with your
                    `apiKey`.
            examples:
              Example:
                value:
                  apiKey: 03c703eb-56cc-46f6-bb63-afb3e302d1bf
                  clientAccessToken: ffb3c8ee-412d-43e5-975a-355e3cc54cf9
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
              examples: {}
        '403':
          description: Forbidden
      security: []
components:
  schemas:
    Authentication:
      title: Authentication
      type: object
      examples:
        - id: 7a9af724-a459-49e5-af08-91fc50373818
          username: f08f1be0-9059-467e-a59e-b3721f434375@api.example.com
          token: >-
            eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmMDhmMWJlMC05MDU5LTQ2N2UtYTU5ZS1iMzcyMWY0MzQzNzVAYXBpLmthcm1hY2hlY2suY29tIiwianRpIjoiN2E5YWY3MjQtYTQ1OS00OWU1LWFmMDgtOTFmYzUwMzczODE4IiwiZ3JvdXBQcm9maWxlSWQiOiI1NTM4MmJmNC02Nzc0LTQ3OGItYmYzMC1kZDI0NWJmZWIwM2MiLCJjb21wYW55SWQiOiJkZGNkY2MzMC1lYTVhLTRiZTktODExOS03OTljZTQzZDk1MWQiLCJncm91cE5hbWUiOiJLYXJtYUNoZWNrIiwiY29tcGFueU5hbWUiOiJLYXJtYUNoZWNrIiwiaXNJbnRlcm5hbCI6MSwiaXNBZG1pbiI6MSwiaWF0IjoxNzAzOTgzNTcyfQ.TvaSgnm0W4XWqYSY1rep4cjPMN2DEDOMIjpKOQMq0zc
          groupProfileId: pe0286f4-ac27-4e36-bfb20-06ae7e392fd2
      required:
        - id
        - username
        - token
        - groupProfileId
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the client. This is the same as the JWT ID
            (`jti` property) of the token.
        username:
          type: string
          description: >-
            The KarmaCheck username of the client. When this endpoint is first
            called for a particular combination of an `apiKey` and a
            `clientAccessToken`, a client user is created in the KarmaCheck
            system whose permissions are scoped to the corresponding group. A
            randomized `username` with `api` in the name is generated to make it
            clear that actions were taken by an API client instead of a user of
            the enterprise dashboard.
        token:
          type: string
          description: >-
            A [JSON Web Token](https://jwt.io/) (JWT) that can be used to
            perform actions like ordering checks and getting results for a group
            of a company. Does not expire, but can be revoked upon request or at
            KarmaCheck's discretion.
        groupProfileId:
          type: string
          description: The ID of the group of the company that the `token` can access.
  securitySchemes:
    JWT:
      type: http
      scheme: bearer

````