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

# Create API Key

> Create a new API key for the current tenant. The full key value is returned **only once** in the response — store it securely.



## OpenAPI

````yaml POST /api/v1/api-keys
openapi: 3.0.3
info:
  title: Uplint API
  version: 0.1.0
  description: >-
    Uplint is a file safety and integrity platform. Upload files through
    context-aware pipelines that automatically validate integrity, detect blank
    or placeholder content, and scan for viruses — all behind a single API.


    This specification covers the core Uplint REST API:


    - **API Keys** — Create and manage scoped API keys for programmatic access.

    - **File Contexts** — Define upload pipelines with per-context rules
    (allowed extensions, size limits, blank/corrupt rejection, virus scanning,
    rate limits, and storage quotas).

    - **Files** — Upload, list, download, inspect, and delete files. Every
    upload runs through the validation pipeline configured on its context.


    All endpoints are tenant-scoped. Authenticate with an API key or JWT token
    via the `Authorization` header.
  contact:
    name: Uplint Team
    url: https://uplint.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.uplint.dev
    description: Production
  - url: http://localhost:8000
    description: Local development
security:
  - BearerAuth: []
tags:
  - name: API Keys
    description: >-
      Create, list, inspect, update, and revoke API keys. Each key carries
      scoped permissions (`upload`, `download`, `metadata`, `delete`, `admin`)
      and is bound to the authenticated tenant.
  - name: File Contexts
    description: >-
      File contexts define upload pipelines. Each context specifies allowed
      extensions, max file size, whether to reject blank or corrupt files, virus
      scanning, rate limits, and storage quotas. Files are always uploaded into
      a context.
  - name: Files
    description: >-
      Upload, list, download, inspect metadata, and delete files. Every upload
      is validated against its context rules before storage.
  - name: Storage Buckets
    description: >-
      Manage the S3 buckets a tenant stores files in. Each tenant can register
      multiple buckets (bring-your-own S3 credentials); one is the **default**
      (fallback) bucket, and file contexts can be routed to any active bucket.
      All storage endpoints require an `admin`-scoped API key.
paths:
  /api/v1/api-keys:
    post:
      tags:
        - API Keys
      summary: Create API key
      description: >-
        Create a new API key for the current tenant. The full key value is
        returned **only once** in the response — store it securely.
      operationId: createApiKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAPIKeyRequest'
            example:
              name: Backend Service
              scopes:
                - upload
                - download
                - metadata
              expires_in_days: 90
      responses:
        '201':
          description: >-
            API key created. The `api_key` field contains the full key — it will
            not be shown again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse_APIKeyCreated'
              example:
                status: SUCCESS
                message: API key created
                data:
                  api_key_id: 6612f1a2c3b4d5e6f7890123
                  api_key: ul_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
                  name: Backend Service
                  scopes:
                    - upload
                    - download
                    - metadata
                  expires_at: '2026-05-11T00:00:00Z'
                timestamp: '2026-02-10T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    CreateAPIKeyRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: A human-readable name for the key.
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/APIKeyScope'
          default:
            - upload
            - download
          description: Permissions granted to this key.
        expires_in_days:
          type: integer
          minimum: 1
          maximum: 365
          nullable: true
          description: Days until the key expires. Omit or pass `null` for no expiry.
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Arbitrary key-value metadata.
    SuccessResponse_APIKeyCreated:
      type: object
      properties:
        status:
          type: string
          enum:
            - SUCCESS
        message:
          type: string
        data:
          $ref: '#/components/schemas/APIKeyCreatedResponse'
        timestamp:
          type: string
          format: date-time
    APIKeyScope:
      type: string
      enum:
        - upload
        - download
        - metadata
        - delete
        - admin
      description: Permission scope for an API key. `admin` grants all permissions.
    APIKeyCreatedResponse:
      type: object
      properties:
        api_key_id:
          type: string
        api_key:
          type: string
          description: The full API key. Shown only once.
        name:
          type: string
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/APIKeyScope'
        expires_at:
          type: string
          format: date-time
          nullable: true
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - ERROR
        message:
          type: string
        errors:
          type: array
          items:
            type: string
        timestamp:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Missing, invalid, or expired authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: ERROR
            message: Invalid or missing API key
            errors:
              - Authentication required
            timestamp: '2026-02-10T12:00:00Z'
    ValidationError:
      description: Request body failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: ERROR
            message: Validation error
            errors:
              - 'name: field required'
            timestamp: '2026-02-10T12:00:00Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Pass an API key or JWT token. API keys can be sent as `Authorization:
        Bearer <key>` or `Authorization: <key>`.

````