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

# Create API Key

> Create a new API key scoped to your workspace.

Create a new API key for the authenticated workspace. Pass a human-readable
`name` and, optionally, an `expires_at` timestamp. The key's raw secret — the
value you send as a bearer token — is returned **only in this response**, so
capture it immediately.

The returned `token` is a 64-character hexadecimal string. Use it on every
subsequent request as `Authorization: Bearer <token>`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.byteport.com/v1/tokens \
    -H "Authorization: Bearer $BYTEPORT_API_KEY" \
    -H "User-Agent: my-app/1.0" \
    -H "Content-Type: application/json" \
    -d '{
      "name":       "production-pipeline",
      "expires_at": "2026-12-31T23:59:59Z"
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.byteport.com/v1/tokens", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
      "User-Agent": "my-app/1.0",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "production-pipeline",
      expires_at: "2026-12-31T23:59:59Z", // optional
    }),
  });
  const key = await res.json();
  console.log(key.token); // store now — never returned again
  ```

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

  res = requests.post(
      "https://api.byteport.com/v1/tokens",
      headers={
          "Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
          "User-Agent": "my-app/1.0",
      },
      json={
          "name": "production-pipeline",
          "expires_at": "2026-12-31T23:59:59Z",  # optional
      },
  )
  key = res.json()
  print(key["token"])  # store now — never returned again
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id":         "9b7e2c1a-4f3d-4a2b-8c1e-2d6f5a0b7c34",
    "name":       "production-pipeline",
    "token":      "7f3a9c1eb2d48056e1a7c93f0d6b8254aa31ff90c4e27b156d8e0fa39b21c7d4",
    "expires_at": "2026-12-31T23:59:59Z"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": 400,
    "message": "name is required"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /v1/tokens
openapi: 3.1.0
info:
  title: Byteport API
  description: >-
    The Byteport API lets you move, share, and manage files across every storage
    location connected to your workspace through a single HTTP interface.
  version: 1.0.0
servers:
  - url: https://api.byteport.com
security:
  - bearerAuth: []
paths:
  /v1/tokens:
    post:
      summary: Create API Key
      description: >-
        Create a new API key (token) scoped to the authenticated workspace. The
        key's raw secret is returned **only in this response** — Byteport stores
        only a SHA-256 hash, so the secret can never be recovered afterward.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: >-
                    Human-readable label for the key, shown in the dashboard
                    alongside its usage metrics. Required and must be non-empty
                    (a blank name is rejected with `400`). Labels do not need to
                    be unique.
                  example: production-pipeline
                expires_at:
                  type: string
                  format: date-time
                  description: >-
                    Optional expiry, as an RFC 3339 / ISO 8601 timestamp. Once
                    this moment passes the key stops authenticating and requests
                    made with it receive `401`. Omit the field to create a key
                    that never expires.
                  example: '2026-12-31T23:59:59Z'
      responses:
        '201':
          description: API key created. The `token` field is present only in this response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreated'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiKeyCreated:
      type: object
      description: >-
        Returned only by Create. The same fields as an API key, plus the
        one-time raw `token`.
      properties:
        id:
          type: string
          description: Unique identifier for the new key (a UUID).
          example: 9b7e2c1a-4f3d-4a2b-8c1e-2d6f5a0b7c34
        name:
          type: string
          description: The label you supplied.
          example: production-pipeline
        token:
          type: string
          description: >-
            The raw API key — a 64-character hexadecimal string. Send it as a
            bearer token on every request (`Authorization: Bearer <token>`).
            Returned **only** in this response; Byteport stores only a hash, so
            it cannot be recovered later.
          example: 7f3a9c1eb2d48056e1a7c93f0d6b8254aa31ff90c4e27b156d8e0fa39b21c7d4
        expires_at:
          type: string
          format: date-time
          description: >-
            The expiry you supplied, echoed back. Omitted if the key never
            expires.
          example: '2026-12-31T23:59:59Z'
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: integer
        message:
          type: string
  responses:
    Error:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````