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

# Issue a new access token

> Issue a new access token

Exchange your `client_id` and `client_secret` for an access token. The token is valid for 15 minutes and must be included in the `Authorization: Bearer <token>` header of all subsequent API requests.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://core.quidkey.com/api/v1/oauth2/token' \
    -H 'Content-Type: application/json' \
    -d '{
      "client_id": "cbad8f7d-41f5-463d-967c-ca825eb65953",
      "client_secret": "98c787a7b57a881e469e64579be9823a302185213de0d3835a766f1e3907982f"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://core.quidkey.com/api/v1/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: 'cbad8f7d-41f5-463d-967c-ca825eb65953',
      client_secret: '98c787a7b57a881e469e64579be9823a302185213de0d3835a766f1e3907982f'
    })
  });

  const { data } = await response.json();
  const { access_token, refresh_token, expires_in } = data;
  console.log('Access token:', access_token);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://core.quidkey.com/api/v1/oauth2/token',
      json={
          'client_id': 'cbad8f7d-41f5-463d-967c-ca825eb65953',
          'client_secret': '98c787a7b57a881e469e64579be9823a302185213de0d3835a766f1e3907982f'
      }
  )

  data = response.json()
  access_token = data['data']['access_token']
  print(f'Access token: {access_token}')
  ```
</RequestExample>

<Tip>
  **Token Lifecycle:**

  * **Validity:** 15 minutes (900 seconds)
  * **Refresh:** Use the `refresh_token` to get a new `access_token` without re-authenticating
  * **Best practice:** Cache tokens and refresh before expiry
</Tip>

<Note>
  Don't have credentials yet? Sign up at [console.quidkey.com](https://console.quidkey.com) to get your `client_id` and `client_secret` for development and production environments.
</Note>


## OpenAPI

````yaml POST /api/v1/oauth2/token
openapi: 3.1.0
info:
  title: Quidkey API
  version: 1.0.0
  description: API documentation for Quidkey Core Services
servers:
  - url: https://core.quidkey.com
    description: Production
security: []
paths:
  /api/v1/oauth2/token:
    post:
      tags:
        - Auth
      summary: Issue a new access token
      description: Issue a new access token
      requestBody:
        required: true
        description: >-
          Request token with given grant type - client_credentials, magic_code,
          google_id_token, or refresh_token
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/auth_TokenRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_TokenResponse'
              example:
                success: true
                data:
                  access_token: example_access_token_xyz789
                  refresh_token: example_refresh_token_abc123
                  token_type: Bearer
                  expires_in: 900
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shared_Error400'
              example:
                success: false
                error:
                  message: Invalid input provided
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_Error401OrChallenge'
components:
  schemas:
    auth_TokenRequest:
      type: object
      discriminator:
        propertyName: grant_type
      title: Token Grant Request
      description: >-
        Request token with given grant type - client_credentials, magic_code,
        google_id_token, or refresh_token
      oneOf:
        - additionalProperties: false
          type: object
          required:
            - grant_type
            - client_id
            - client_secret
          properties:
            grant_type:
              const: client_credentials
              type: string
            client_id:
              format: uuid
              description: The client ID of the partner or merchant
              examples:
                - 547544c3-eeac-492e-8df9-5a52ca4e6bdf
              type: string
            client_secret:
              description: The client secret of the partner or merchant
              examples:
                - >-
                  b717adcac3f26e8034574021fa647cd7d4edd67b615046df387f6712c3601048
              type: string
        - additionalProperties: false
          type: object
          required:
            - grant_type
            - email
          properties:
            grant_type:
              const: magic_code
              type: string
            email:
              format: email
              description: Admin email address
              examples:
                - admin@example.com
              type: string
            code:
              minLength: 6
              maxLength: 6
              description: The 6-character verification code sent to email
              examples:
                - abc123
              type: string
            ctx:
              pattern: >-
                ^(global|(partner|merchant):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
              description: 'Optional context: "global", "partner:uuid", or "merchant:uuid"'
              examples:
                - partner:550e8400-e29b-41d4-a716-446655440000
              type: string
        - additionalProperties: false
          type: object
          required:
            - grant_type
            - id_token
          properties:
            grant_type:
              const: google_id_token
              type: string
            id_token:
              description: Google ID token obtained from Google Sign-In
              examples:
                - eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
              type: string
            ctx:
              pattern: >-
                ^(global|(partner|merchant):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
              description: 'Optional context: "global", "partner:uuid", or "merchant:uuid"'
              examples:
                - partner:550e8400-e29b-41d4-a716-446655440000
              type: string
        - additionalProperties: false
          type: object
          required:
            - grant_type
            - refresh_token
          properties:
            grant_type:
              const: refresh_token
              type: string
            refresh_token:
              description: The refresh token obtained from a previous token request
              examples:
                - eyJhbGciOiJIUzI1NiIs...
              type: string
            ctx:
              pattern: >-
                ^(global|(partner|merchant):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
              description: >-
                Optional context to switch to: "global", "partner:uuid", or
                "merchant:uuid".
              examples:
                - partner:550e8400-e29b-41d4-a716-446655440000
              type: string
    auth_TokenResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          description: Indicates if the request was successful
          examples:
            - true
          type: boolean
        data:
          additionalProperties: false
          type: object
          required:
            - access_token
            - token_type
            - expires_in
          properties:
            access_token:
              description: The access token to be used for authenticated requests
              examples:
                - example_access_token_xyz789
              type: string
            refresh_token:
              description: >-
                The refresh token used to obtain a new access token. Returned
                only when a token is first issued (client_credentials,
                magic_code, google_id_token grants); the refresh grant does not
                return a new refresh token, so the original is reused until it
                expires.
              examples:
                - example_refresh_token_abc123
              type: string
            token_type:
              description: The type of token issued
              examples:
                - Bearer
              const: Bearer
              type: string
            expires_in:
              description: The number of seconds until the access token expires
              examples:
                - 900
              type: number
    shared_Error400:
      title: Bad Request Error
      description: 400 Bad Request Error Response
      type: object
      required:
        - success
        - error
      properties:
        success:
          description: Always false for error responses
          examples:
            - false
          const: false
          type: boolean
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              allOf:
                - description: Error code for the specific error type
                  examples:
                    - INVALID_INPUT
                  type: string
                - description: Error code for the specific error type
                  examples:
                    - VALIDATION_ERROR
                  type: string
            message:
              description: Human-readable error message
              examples:
                - Invalid input provided
              type: string
            metadata:
              additionalProperties: true
              description: >-
                Additional error context. For VALIDATION_ERROR, includes a
                per-field `errors` array.
              type: object
              properties:
                errors:
                  type: array
                  items:
                    type: object
                    required:
                      - field
                      - message
                    properties:
                      field:
                        type: string
                      message:
                        type: string
    auth_Error401OrChallenge:
      oneOf:
        - title: Unauthorized Error
          description: 401 Unauthorized Error Response
          type: object
          required:
            - success
            - error
          properties:
            success:
              description: Always false for error responses
              examples:
                - false
              const: false
              type: boolean
            error:
              type: object
              required:
                - code
                - message
              properties:
                code:
                  allOf:
                    - description: Error code for the specific error type
                      examples:
                        - INVALID_INPUT
                      type: string
                    - const: UNAUTHORIZED
                      type: string
                message:
                  description: Human-readable error message
                  examples:
                    - Invalid input provided
                  type: string
        - additionalProperties: false
          type: object
          required:
            - success
            - error
          properties:
            success:
              description: Always false for challenge responses
              examples:
                - false
              const: false
              type: boolean
            error:
              type: object
              required:
                - code
                - message
                - challenge
              properties:
                code:
                  description: Error code indicating a challenge must be completed
                  examples:
                    - CHALLENGE_REQUIRED
                  const: CHALLENGE_REQUIRED
                  type: string
                message:
                  description: Human-readable message
                  examples:
                    - Verification code sent to email
                  type: string
                challenge:
                  additionalProperties: false
                  type: object
                  required:
                    - id
                    - type
                    - expires_at
                  properties:
                    id:
                      description: >-
                        Identifier for the challenge (typically the email
                        address)
                      examples:
                        - admin@example.com
                      type: string
                    type:
                      description: The type of challenge issued
                      examples:
                        - email_code
                      const: email_code
                      type: string
                    expires_at:
                      format: date-time
                      description: ISO 8601 timestamp when the challenge expires
                      examples:
                        - '2025-12-15T15:30:00.000Z'
                      type: string

````