---
title: "Create workspace"
method: POST
path: "/v2/storage/workspaces"
tags: ["Workspaces"]
---

# Create workspace

`POST /v2/storage/workspaces`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/workspaces`
- Auth: one of:
  - API key in header `X-StorageApi-Token`
  - API key in header `X-KBC-ManageApiToken`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/keboola/apis/keboola-storage-api/docs/v2/storage/workspaces/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new workspace and returns its credentials. Workspaces provide a playground for your data. You can load data
from your storage, explore or modify it and then, optionally, load it back to storage tables. A workspace is represented
by access credentials to a storage backend with permissions to write to the workspace specific database schema.

Set `async=true` to create the workspace in a background job. Calling the endpoint with `async=false` is deprecated.

To create a workspace bound to a component configuration (including a reader workspace), use the
`/components/{componentId}/configs/{configurationId}/workspaces` variant of this endpoint.

All workspaces endpoints can be used with `default` for the `branchId` parameter, which emulates the call without
a development branch: `GET /v2/storage/workspaces` is the same as `GET /v2/storage/branch/default/workspaces`.

## Path parameters

- `componentId` string
- `configurationId` string

## Query parameters

- `async` boolean

## Headers

- `X-KBC-Backend` object
  - `context` string, nullable

## Request body

- CreateWorkspaceRequest
  - `backend` 'snowflake' | 'bigquery' | 'abs', nullable: Workspace backend type.
  - `backendSize` string, nullable: Requested backend size (Snowflake only).
  - `readOnlyStorageAccess` boolean, nullable: Enable read-only storage access.
  - `networkPolicy` 'system' | 'user' | 'not-defined', nullable: Network policy for the workspace.
  - `loginType` 'null' | 'default' | 'snowflake-legacy-service' | 'snowflake-person-sso' | 'snowflake-person-keypair' | 'snowflake-service-keypair' | 'none' | 'governed', nullable: Preferred login type. Use "none" to create a workspace without credentials for QueryService. Create direct connection credentials later using the workspace credentials endpoint. Use "governed" (Snowflake and BigQuery, no "publicKey") to create a workspace that only QueryService can read: it has no login, nobody else can obtain its credentials, and password reset, public key, SSO and native query are refused. For the "snowflake" backend, "default" and "snowflake-legacy-service" are rejected because they resolve to password authentication, which Snowflake no longer supports; use "snowflake-service-keypair" or "snowflake-person-keypair" with "publicKey", or "none".
  - `publicKey` string, nullable: RSA public key for key pair login.
  - `useCase` 'normal' | 'reader', nullable: Workspace use case.
  - `configurationVersion` integer, nullable: Pin workspace to a specific configuration version.

## Response `201`

Synchronous call response (`async=false`). The password (or key/connection string) is returned only here and cannot be retrieved later.

- WorkspaceCreatedResponse: Workspace detail extended with the freshly created secret. The secret is not stored and is returned only once, right after the workspace is created.
  - `id` integer, required: ID of the workspace.
  - `type` 'file' | 'table', required: Type of the workspace.
  - `name` string, nullable, required: Name of the workspace (schema name for table type).
  - `component` string, nullable, required: ID of the component that created the workspace.
  - `configurationId` string, nullable, required: ID of the configuration that created the workspace.
  - `configurationVersion` integer, nullable, required: Pinned configuration version.
  - `created` string, required: Date and time of workspace creation, ISO 8601 with a `+hhmm` offset.
  - `connection` union, required: Connection details for the workspace.
    - object
      - `backend` 'snowflake' | 'synapse' | 'exasol' | 'teradata' | 'bigquery' | 'postgres' | 'ducklake', required: Workspace backend type.
      - `region` string, required: Region of the workspace backend.
      - `host` string, required: Hostname of the workspace backend.
      - `database` string, nullable, required: Database name (project name for Snowflake).
      - `schema` string, nullable, required: Schema name.
      - `warehouse` string, nullable, required: Warehouse name (for Snowflake).
      - `user` string: Username for connecting to the workspace. Empty when loginType is "none" or "governed". Absent for a BigQuery workspace created with a key, which returns `credentials` instead.
      - `loginType` 'default' | 'snowflake-legacy-service' | 'snowflake-person-sso' | 'snowflake-person-keypair' | 'snowflake-service-keypair' | 'none' | 'governed', required: Login type used for the connection. Value "none" means the workspace has no direct credentials and is intended for QueryService. Value "governed" means the same, and in addition only QueryService can obtain credentials for it. Create direct connection credentials later using the workspace credentials endpoint.
      - `ssoLoginAvailable` boolean, required: Indicates if SSO login is available.
      - `account` string: Snowflake account locator. Present only for Snowflake workspaces.
      - `role` string, nullable: Snowflake role of the workspace user. Present only for Snowflake workspaces.
      - `password` string: Password of the workspace user. Present only for a table workspace other than BigQuery created with a password login type.
      - `credentials` object: Google service account key. Present only for a BigQuery workspace created with a key; the `user` key is omitted in that case.
        - `type` string
        - `project_id` string
        - `private_key_id` string
        - `private_key` string
        - `client_email` string
        - `client_id` string
        - `auth_uri` string
        - `token_uri` string
        - `auth_provider_x509_cert_url` string
        - `client_x509_cert_url` string
    - object
      - `backend` string, required: File storage backend type (e.g., azure, aws).
      - `container` string, nullable, required: Container name for file storage.
      - `region` string, required: Region of the file storage.
      - `connectionString` string: SAS connection string. Present only for a file (ABS) workspace created with a secret.
  - `backendSize` string, nullable, required: Size of the backend (e.g., for Snowflake).
  - `statementTimeoutSeconds` integer, required: Statement timeout in seconds.
  - `creatorToken` object, required
    - `id` integer, required: ID of the token that created the workspace; 0 when the creator is not backed by a token.
    - `description` string, nullable, required: Description of the token.
  - `actor` ActorResponse, required: Who performed the action and through which credential.
    - `type` 'token' | 'session' | 'pat' | 'system', required: Credential the action came through: a Storage token, a programmatic session, a personal access token, or system work.
    - `id` string, required: Token id as a string, session or personal access token UUID, or the system subject.
    - `name` string, required: Token description, the admin email for a session or personal access token, or the system label, as it was when the action happened.
    - `adminId` integer, nullable, required: Admin behind the credential; null for a token without an admin, for system work, and when the admin was not recorded (an object whose creator is known only from its token columns, including rows backfilled from them).
  - `readOnlyStorageAccess` boolean, required: Indicates if read-only storage access is enabled.
  - `platformUsageType` 'service' | 'user' | 'reader', nullable, required: Platform usage type.
  - `state` 'active' | 'deactivated', required: Lifecycle state of the workspace. A deactivated workspace is kept listed so its owner can delete it, but its backend identity is disabled and cannot be connected to; contact support to reactivate it.
  - `lastActivityAt` string, nullable, required: Last observed workspace use (backend login or Storage job), ISO 8601 with a `+hhmm` offset. May be a seeded floor for an unused workspace; null when unknown.
  - `warnAt` string, nullable, required: Projected date retention would warn this workspace, ISO 8601 with a `+hhmm` offset. It can move when the workspace is used; null when retention does not apply or activity has not been synced recently.
  - `deactivateAt` string, nullable, required: When retention will deactivate this unused workspace, ISO 8601 with a `+hhmm` offset. Null unless the owner has been warned. Connecting to the workspace cancels it. Can lie in the past while retention only notifies.
  - `deleteAt` string, nullable, required: When retention will delete this deactivated workspace, ISO 8601 with a `+hhmm` offset. Null unless the workspace is deactivated. Support can reactivate it until then.

## Other responses

- `202`: Asynchronous call response (`async=true`) that creates a new `workspaceCreate` job. To see the job detail use the Job Detail endpoint.
- `400`: Returned when the request is invalid, e.g. unsupported backend or backend size (`workspace.backendNotSupported`), dynamic backend size feature not enabled, invalid reader/direct-grant configuration, or a backend driver error.
- `403`: Returned when the token lacks write access to a direct grant output mapping bucket, or when the user has the read-only role in the project.
- `404`: Returned when the component or configuration is not found (configuration workspace variant only).
- `501`: Returned when creating a configuration workspace in a Snowflake Partner Connect limited project.

---

[API](https://skmtc.dev/keboola/apis/keboola-storage-api.md) - [All operations](https://skmtc.dev/keboola/apis/keboola-storage-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keboola/apis/keboola-storage-api/revisions/34b5ceac0317?raw)