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

# Rotate API key

> Rotate your API key.

Creates a new API key and deprecates the current active key.
The old key remains valid for 7 days (grace period) to allow migration.

This is the recommended way to rotate keys without service disruption.



## OpenAPI

````yaml openapi.json post /v1/keys/rotate
openapi: 3.1.0
info:
  title: DocIntell API
  description: >-

    # DocIntell API


    **Turn Documents into Data. Keep the Source Safe.**


    Financial document intelligence platform that turns PDFs into queryable data
    while keeping source files secure and compliant.


    ## Features


    - **Document Ingestion**: Upload PDFs with SEC 17a-4 compliant immutable
    storage

    - **Schema Projection**: Query extracted data with custom schemas (not data
    dumps!)

    - **Multi-Schema Support**: Same document, multiple query patterns

    - **Webhook Delivery**: Async notifications on job completion

    - **Row-Level Security**: Multi-tenant isolation built-in


    ## Authentication


    All API endpoints (except `/health`, `/`, `/docs`, and `/redoc`) require API
    key authentication.


    Include your API key in the `Authorization` header:


    ```

    Authorization: Bearer dk_live_<your_key>

    ```


    Test keys start with `dk_test_`, production keys with `dk_live_`.


    ## Rate Limiting


    Per-tenant rate limits:

    - **Document ingestion**: 100 documents/hour

    - **Projection queries**: 1,000 requests/hour

    - **Schema operations**: 10 creates/hour


    Rate limit info is returned in response headers:

    - `X-RateLimit-Limit`: Maximum requests allowed

    - `X-RateLimit-Remaining`: Remaining requests in window

    - `X-RateLimit-Reset`: Unix timestamp when limit resets


    ## Error Handling


    All errors follow RFC 7807 Problem Details format:


    ```json

    {
      "error": "error_code",
      "message": "Human-readable description",
      "details": {}
    }

    ```


    Common error codes:

    - `unauthorized` (401): Missing or invalid API key

    - `rate_limit_exceeded` (429): Too many requests

    - `invalid_file_type` (400): Only PDFs supported

    - `file_too_large` (413): File exceeds size limit (default 100MB,
    configurable via MAX_UPLOAD_SIZE_MB)

    - `job_not_found` (404): Job ID doesn't exist or doesn't belong to tenant


    ## Getting Started


    1. Obtain API key from dashboard

    2. Upload PDF: `POST /v1/documents`

    3. Poll status: `GET /v1/documents/{document_id}/status`

    4. Query results: `POST /v1/documents/{document_id}/project`


    Full documentation: [https://docs.docintel.com](https://docs.docintel.com)
        
  contact:
    name: DocIntell Support
    url: https://docintel.com/support
    email: support@docintel.com
  license:
    name: Proprietary
    url: https://docintel.com/terms
  version: 0.1.0
servers:
  - url: http://localhost:8000
    description: Local development
  - url: https://api.docintell.com
    description: Production API
  - url: https://api-staging.docintell.com
    description: Staging environment
security:
  - bearerAuth: []
tags:
  - name: health
    description: Health check operations. Verify service and dependency connectivity.
    x-mint-tag-group: System
  - name: api_keys
    description: API key management operations. Create, list, and revoke API keys.
    x-mint-tag-group: Management
  - name: documents
    description: Document ingestion operations. Upload PDFs for extraction.
    x-mint-tag-group: Core
  - name: jobs
    description: >-
      Job status and query operations. Check extraction status and query
      results.
    x-mint-tag-group: Core
  - name: document-types
    description: >-
      Document type schemas. List and retrieve extraction schema definitions for
      financial document types.
  - name: webhooks
    description: >-
      Webhook configuration management. Create, update, and manage webhook
      endpoints for job completion notifications.
    x-mint-tag-group: Integrations
  - name: stats
    description: Analytics and metrics endpoints. Get document, job, and schema statistics.
  - name: views
    description: >-
      View management for consumption layer. Define field subsets for querying
      extraction data.
paths:
  /v1/keys/rotate:
    post:
      tags:
        - api_keys
      summary: Rotate API key
      description: |-
        Rotate your API key.

        Creates a new API key and deprecates the current active key.
        The old key remains valid for 7 days (grace period) to allow migration.

        This is the recommended way to rotate keys without service disruption.
      operationId: rotate_api_key_v1_keys_rotate_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAPIKeyRequest'
      responses:
        '201':
          description: New API key created and old key deprecated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotateAPIKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateAPIKeyRequest:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: Human-readable name for this API key
        environment:
          type: string
          enum:
            - live
            - test
          title: Environment
          description: 'Key environment: ''live'' for production, ''test'' for testing'
          default: live
      type: object
      required:
        - name
      title: CreateAPIKeyRequest
      description: |-
        Request schema for creating a new API key (POST /v1/keys).

        Attributes:
            name: Human-readable name for the API key (e.g., "Production API Key")
            environment: Key environment - "live" for production, "test" for testing (default: "live")
      examples:
        - environment: live
          name: Production API Key
    RotateAPIKeyResponse:
      properties:
        new_key:
          $ref: '#/components/schemas/CreateAPIKeyResponse'
          description: The newly created API key (includes plaintext key, shown only once)
        deprecated_key:
          $ref: '#/components/schemas/APIKeyResponse'
          description: The old key that was deprecated (with grace period information)
      type: object
      required:
        - new_key
        - deprecated_key
      title: RotateAPIKeyResponse
      description: |-
        Response for API key rotation (POST /v1/keys/rotate).

        Returns the new key and information about the deprecated old key.
        The old key remains active for 7 days (grace period) to allow migration.

        WARNING: The api_key field in new_key is shown only in this response.
        Store it securely immediately - it cannot be retrieved again.
      examples:
        - deprecated_key:
            created_at: '2024-01-01T10:30:00Z'
            deprecated_at: '2024-01-15T10:30:00Z'
            environment: live
            grace_period_days_remaining: 7
            grace_period_ends_at: '2024-01-22T10:30:00Z'
            is_active: true
            key_id: 550e8400-e29b-41d4-a716-446655440000
            key_prefix: dk_live_
            key_suffix: xY9z
            last_used_at: '2024-01-15T10:29:00Z'
            name: Production API Key
            status: deprecated
          new_key:
            api_key: dk_live_newKeyXYZ123456789abcdefghijklmnop
            created_at: '2024-01-15T10:30:00Z'
            environment: live
            key_id: 770e8400-e29b-41d4-a716-446655440002
            name: Production API Key
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateAPIKeyResponse:
      properties:
        key_id:
          type: string
          format: uuid
          title: Key Id
          description: Unique API key identifier
        name:
          type: string
          title: Name
          description: Human-readable name for this API key
        api_key:
          type: string
          title: Api Key
          description: >-
            The actual API key (shown ONLY in this response - cannot be
            retrieved later)
        environment:
          type: string
          title: Environment
          description: Key environment (live or test)
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Key creation timestamp (ISO 8601)
      type: object
      required:
        - key_id
        - name
        - api_key
        - environment
        - created_at
      title: CreateAPIKeyResponse
      description: >-
        Response for newly created API key (shown only once).


        WARNING: The api_key field is shown only in this response.

        Once this response is received, the plaintext key cannot be retrieved
        again.

        Store it securely immediately.
      examples:
        - api_key: dk_live_abcdefghijklmnopqrstuvwxyz1234567890ABC
          created_at: '2024-01-15T10:30:00Z'
          environment: live
          key_id: 550e8400-e29b-41d4-a716-446655440000
          name: Production API Key
    APIKeyResponse:
      properties:
        key_id:
          type: string
          format: uuid
          title: Key Id
          description: Unique API key identifier
        name:
          type: string
          title: Name
          description: Human-readable name for this API key
        key_prefix:
          type: string
          title: Key Prefix
          description: First 8 characters of the API key (e.g., 'dk_live_')
        key_suffix:
          type: string
          title: Key Suffix
          description: Last 4 characters of the API key for masked display
        environment:
          type: string
          title: Environment
          description: Key environment (live or test)
        is_active:
          type: boolean
          title: Is Active
          description: Whether the key is currently active
        status:
          type: string
          enum:
            - active
            - deprecated
            - expired
            - revoked
          title: Status
          description: Current key status
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Key creation timestamp (ISO 8601)
        last_used_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Used At
          description: Last time the key was used (ISO 8601, null if never used)
        deprecated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Deprecated At
          description: When the key was deprecated (ISO 8601, null if not deprecated)
        grace_period_ends_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Grace Period Ends At
          description: When the grace period expires (ISO 8601, null if not deprecated)
        grace_period_days_remaining:
          anyOf:
            - type: integer
            - type: 'null'
          title: Grace Period Days Remaining
          description: >-
            Days remaining in grace period (null if not deprecated, 0 if
            expired)
      type: object
      required:
        - key_id
        - name
        - key_prefix
        - key_suffix
        - environment
        - is_active
        - status
        - created_at
      title: APIKeyResponse
      description: |-
        API key response with masked key for list operations.

        Key Status Values:
            - 'active': Key is working normally
            - 'deprecated': Key is deprecated but still works (in grace period)
            - 'expired': Grace period ended, key no longer works
            - 'revoked': Key was manually revoked
      examples:
        - created_at: '2024-01-15T10:30:00Z'
          environment: live
          is_active: true
          key_id: 550e8400-e29b-41d4-a716-446655440000
          key_prefix: dk_live_
          key_suffix: xY9z
          last_used_at: '2024-01-15T12:45:00Z'
          name: Production API Key
          status: active
        - created_at: '2024-01-01T10:30:00Z'
          deprecated_at: '2024-01-15T10:30:00Z'
          environment: live
          grace_period_days_remaining: 5
          grace_period_ends_at: '2024-01-22T10:30:00Z'
          is_active: true
          key_id: 660e8400-e29b-41d4-a716-446655440001
          key_prefix: dk_live_
          key_suffix: aBc1
          last_used_at: '2024-01-15T12:45:00Z'
          name: Old Production Key
          status: deprecated
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key authentication. Format: dk_test_<key> or dk_live_<key>'

````