> ## Documentation Index > Fetch the complete documentation index at: https://docs.boat.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a scoped API key > Create an API key limited to some actions, sandboxes or environments, with an expiry. Same as boat api-key create. ## OpenAPI ````yaml openapi/boat-v1.yaml POST /api-keys/scoped openapi: 3.1.0 info: title: Boat Public API v1 version: 1.0.0 description: > Public JSON API for creating, operating, prompting, observing, and exposing sandboxes from backend services, CI jobs, hosted workers, and Boat automation products. The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1. servers: - url: https://boat.dev/api/v1 security: - BoatBearerAuth: [] tags: - name: Boat description: >- Unified Boat account, setup, lifecycle, prompting, event history, desktop access, and SSH operations. paths: /api-keys/scoped: post: tags: - Boat summary: Create a scoped API key description: >- Creates a scoped, expiring API key. Requires a dashboard/CLI session or an admin-scoped token. The secret is returned once. This dedicated path returns a typed 503 until scoped credential creation is activated. operationId: createScopedApiKey requestBody: required: true content: application/json: schema: type: object properties: name: type: string ttl: type: string description: Duration such as 90d, 24h, or seconds. Max 365d. examples: - 90d preset: type: string enum: - read-only - full-sandbox - ci - admin actions: type: array items: type: string sandboxIds: type: array items: type: string environmentIds: type: array items: type: string responses: '201': description: Created key metadata plus the one-time secret. content: application/json: schema: $ref: '#/components/schemas/ApiKeySecretResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '503': description: Scoped credential creation has not been activated yet. content: application/json: schema: type: object required: - error - message - scopedCreationEnabled properties: error: type: string enum: - scoped_api_key_creation_disabled message: type: string scopedCreationEnabled: type: boolean examples: - false components: schemas: ApiKeySecretResponse: allOf: - $ref: '#/components/schemas/SuccessBase' - type: object required: - apiKey - secret - apiKeys properties: apiKey: $ref: '#/components/schemas/ApiKey' secret: type: string description: Raw secret returned once. Store it before closing the response. apiKeys: type: array items: $ref: '#/components/schemas/ApiKey' SuccessBase: type: object required: - ok - type properties: ok: type: boolean examples: - true type: type: string description: Stable success envelope discriminator added by v1. ApiKey: type: object required: - id - name - credentialLane - keyPrefix - keyLastFour - sandboxId - createdAt - lastUsedAt - usage - resources properties: id: type: string examples: - sak_123 name: type: string examples: - Production worker credentialLane: type: string enum: - legacy - scoped-v1 description: >- Credential storage lane. Scoped secrets are never stored in the legacy hash column. keyPrefix: type: string examples: - boat_live keyLastFour: type: string examples: - 9abc sandboxId: type: - string - 'null' description: >- Sandbox ID for a platform-managed machine key, or null for a user-created key. createdAt: type: string format: date-time lastUsedAt: type: - string - 'null' format: date-time usage: $ref: '#/components/schemas/ApiKeyRequestUsage' resources: $ref: '#/components/schemas/ApiKeyResourceTotals' expiresAt: type: - string - 'null' format: date-time expired: type: boolean expiringSoon: type: boolean scope: type: object properties: expiresAt: type: - string - 'null' format: date-time actions: type: array items: type: string sandboxes: oneOf: - type: string enum: - '*' - type: array items: type: string environments: oneOf: - type: string enum: - '*' - type: array items: type: string grandfathered: type: boolean ErrorEnvelope: type: object required: - ok - type - status - code - message - error - requestId properties: ok: type: boolean examples: - false type: type: string examples: - sandbox.error status: type: integer examples: - 409 code: type: string examples: - provider_not_configured message: type: string examples: - Prompting is locked until Codex is configured on the Agents page. requestId: type: string examples: - req_01HX... error: type: object required: - code - message - status properties: code: type: string message: type: string status: type: integer details: type: object additionalProperties: true ApiKeyRequestUsage: type: object required: - requests - windowDays properties: requests: type: integer minimum: 0 description: >- Requests authenticated with this key during the current UTC day and the previous 29 UTC days. examples: - 1842 windowDays: type: integer const: 30 ApiKeyResourceTotals: type: object required: - total - sandboxes - agents properties: total: type: integer minimum: 0 sandboxes: type: integer minimum: 0 agents: type: integer minimum: 0 responses: BadRequest: description: Invalid request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid: value: ok: false type: sandbox.error status: 400 code: invalid_json message: Request body must be valid JSON. error: code: invalid_json message: Request body must be valid JSON. status: 400 requestId: req_01HX... Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: unauthorized: value: ok: false type: sandbox.error status: 401 code: unauthorized message: Unauthorized error: code: unauthorized message: Unauthorized status: 401 requestId: req_01HX... Forbidden: description: Authenticated token is not allowed to perform this action. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: forbidden: value: ok: false type: sandbox.error status: 403 code: forbidden message: Forbidden error: code: forbidden message: Forbidden status: 403 requestId: req_01HX... securitySchemes: BoatBearerAuth: type: http scheme: bearer bearerFormat: sandbox_api_key description: >- Boat bearer token in the form `boat_...`. Service API keys authenticate sandbox operations. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.