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

# Create S3 Access Key

> Mint a new S3 credential pair usable against the `/storage/v1/s3`
protocol gateway. The plaintext `secretAccessKey` in the response
is returned **exactly once** — it is encrypted at rest and can
never be retrieved again. If you lose it, revoke and re-create.

Limits:
- 50 keys per project (hard cap, enforced transactionally).
- Rate-limited to 20 management requests per 15 min per IP.




## OpenAPI

````yaml https://raw.githubusercontent.com/InsForge/InsForge/main/openapi/storage.yaml post /api/storage/s3/access-keys
openapi: 3.0.3
info:
  title: Insforge Storage API
  version: 2.0.0
  description: Bucket-based storage system similar to S3
servers: []
security: []
paths:
  /api/storage/s3/access-keys:
    post:
      tags:
        - S3 Access Keys
      summary: Create S3 Access Key
      description: |
        Mint a new S3 credential pair usable against the `/storage/v1/s3`
        protocol gateway. The plaintext `secretAccessKey` in the response
        is returned **exactly once** — it is encrypted at rest and can
        never be retrieved again. If you lose it, revoke and re-create.

        Limits:
        - 50 keys per project (hard cap, enforced transactionally).
        - Rate-limited to 20 management requests per 15 min per IP.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateS3AccessKeyRequest'
      responses:
        '201':
          description: Access key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/S3AccessKeyWithSecret'
              example:
                data:
                  id: 11111111-1111-1111-1111-111111111111
                  accessKeyId: INSFABC123DEF456GH78
                  secretAccessKey: x7K2-a_pL9qRs4N8vYzWcE1fH5gJ3mUtBoD6ViXk
                  description: backup-script
                  createdAt: '2026-04-22T00:00:00Z'
                  lastUsedAt: null
        '400':
          description: Validation error or 50-key cap reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key / admin token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded (20 requests / 15 min / IP)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - apiKey: []
components:
  schemas:
    CreateS3AccessKeyRequest:
      type: object
      properties:
        description:
          type: string
          maxLength: 200
          description: Optional label to help you identify the key later
          example: backup-script
    S3AccessKeyWithSecret:
      allOf:
        - $ref: '#/components/schemas/S3AccessKey'
        - type: object
          required:
            - secretAccessKey
          properties:
            secretAccessKey:
              type: string
              description: |
                40-character base64url secret. **Returned only once** in the
                create response — retrieve, store, and keep it secret.
              example: x7K2-a_pL9qRs4N8vYzWcE1fH5gJ3mUtBoD6ViXk
    ErrorResponse:
      type: object
      required:
        - error
        - message
        - statusCode
      properties:
        error:
          type: string
          description: Error code for programmatic handling
          example: VALIDATION_ERROR
        message:
          type: string
          description: Human-readable error message
          example: Invalid request
        statusCode:
          type: integer
          description: HTTP status code
          example: 400
        nextActions:
          type: string
          description: Suggested action to resolve the error
          example: Check your request parameters
    S3AccessKey:
      type: object
      description: An S3 access key record (without the plaintext secret).
      required:
        - id
        - accessKeyId
        - description
        - createdAt
        - lastUsedAt
      properties:
        id:
          type: string
          format: uuid
          description: Internal UUID of the access key record
          example: 11111111-1111-1111-1111-111111111111
        accessKeyId:
          type: string
          pattern: ^INSF[A-Z0-9]{16}$
          description: 20-character access key id with fixed `INSF` prefix
          example: INSFABC123DEF456GH78
        description:
          type: string
          nullable: true
          description: User-supplied label (max 200 chars)
          example: backup-script
        createdAt:
          type: string
          format: date-time
          example: '2026-04-22T00:00:00Z'
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
          description: Updated asynchronously after each successful SigV4 verification
          example: null
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````