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

# Create token

> This handles authentication for consulting firm clients and returns a token to be used for accessing protected resources.

`client_id` and `client_secret` are required to uniquely identify the consulting firm during authentication.



## OpenAPI

````yaml https://app.teamcaredental.com/openapi-vendors-v2.json post /auth/token
openapi: 3.1.0
info:
  title: TeamCare Vendor API (v2)
  version: 2.0.0
  description: >-
    Version 2 of the TeamCare Vendor API. HIPAA-compliant and opt-in.


    ## What changed from v1


    The data endpoints and response shapes are identical to v1 — **only how you
    address a location changes.** In v1 the location lived in every URL
    (`/locations/{location_id}/patients`). In v2 you request a **slot** for a
    location once, then send the returned `request_key` in the
    `X-Vendor-Request-Key` header; `location_id` is gone from the data routes.


    ## Request cycle


    1. `POST /auth/token` → JWT (unchanged from v1).

    2. `GET /organizations`, `GET /locations` → pick a `location_id`.

    3. `POST /locations/{location_id}/slots` → `{ request_key, expires_at }`.

    4. Call any data endpoint with header `X-Vendor-Request-Key: <request_key>`
    (no `location_id` in the path).


    ## Minimal changes to migrate


    - Point your base URL at `https://api.teamcaredental.com/api/v2/vendors` (v2
    is served from `api.teamcaredental.com`, not `app.teamcaredental.com`).

    - Call the slot endpoint **once per location**.

    - Drop `/locations/{location_id}` from your data paths and add the
    `X-Vendor-Request-Key` header.

    - Everything else — authentication, Ransack `q` filters, pagination,
    response shapes — is unchanged.


    ## Slot validity, cooldown & quota


    - **Validity:** a `request_key` is valid for **6 hours** — the same lifetime
    as the access token. After that it stops authorizing and you must request a
    new slot.

    - **Cooldown:** you can only re-request the **same** location's slot once
    every **2 minutes**. Within the cooldown the slot endpoint returns `429`
    with a `retry_after` (seconds).

    - **Quota:** each firm may hold up to its `concurrent_slots` quota (default
    **10**) active request keys at once, so data for at most 10 locations can be
    pulled concurrently. Requesting an 11th slot trims the oldest key, so its
    `request_key` stops authorizing immediately and any in-flight requests using
    it fail with `401`. To raise the quota above 10, contact TeamCare support.

    - **Rate limit:** the slot endpoint accepts at most 10 requests per 10
    seconds per token.


    ## Recommended usage


    Request a slot for a location and pull **all** of that location's data in
    one pass before moving on — don't re-request slots per call or churn between
    locations. If you fan out across locations in parallel, keep the fan-out at
    or below your quota: once an 11th slot is requested, the oldest
    `request_key` is invalidated even if a sync is still running on it.


    See the [changelog](https://docs.teamcaredental.com/changelog) for the full
    list of changes from v1.
servers:
  - url: https://api.teamcaredental.com/api/v2/vendors
security:
  - bearerAuth: []
paths:
  /auth/token:
    post:
      tags:
        - Authentication
      summary: Create token
      description: >-
        This handles authentication for consulting firm clients and returns a
        token to be used for accessing protected resources.


        `client_id` and `client_secret` are required to uniquely identify the
        consulting firm during authentication.
      operationId: authentication_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  example: '{{client_id}}'
                client_secret:
                  type: string
                  example: '{{client_secret}}'
            example:
              client_id: '{{client_id}}'
              client_secret: '{{client_secret}}'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid client_id or client_secret.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
              example:
                errors: Invalid Credentials
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
              example:
                errors: resource not found
        '422':
          description: The request could not be processed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
              example:
                errors: ...
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT returned by POST /auth/token. Valid for six hours.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.