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

# Create API Key

Use this API to create a new API key for a workspace.

> [!NOTE]
>
> This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers.

> [!NOTE]
>
> Creating a **`production`** API key is gated. The workspace must be explicitly enabled for self‑serve production key creation and must already be on a paid plan. See [Production API Keys](#production-api-keys) below.

# Endpoint

`POST https://api.velt.dev/v2/workspace/apikey/create`

# Headers

**x-velt-workspace-id** `string` *required*

Your Workspace ID.

**x-velt-workspace-auth-token** `string` *required*

Your workspace [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**ownerEmail** `string` *required*

Email address of the API key owner. Must be a valid email.

**type** `string` *required*

API key type. Accepted values: `"testing"` or `"production"`.

**persistenceDBRegion** `string`

Provide this only for type: `"production"`. Accepts any supported region from [Supported Regions](https://velt.dev/docs/security/supported-regions.md).

**createAuthToken** `boolean`

Whether to create an auth token along with the API key. Recommended: `true`.

**apiKeyName** `string`

Display name for the API key.

**allowedDomains** `string[]`

List of domains allowed to use this API key.

**addLocalHostToAllowedDomains** `boolean`

Whether to automatically add localhost to allowed domains.

**useEmailService** `boolean`

Whether to enable the email service for this API key.

**useWebhookService** `boolean`

Whether to enable the webhook service for this API key.

**useNotificationService** `boolean`

Whether to enable the in‑app notification service for this API key.

**setDefaultNotificationTriggers** `boolean`

Seed the default notification triggers when enabling the notification service.

**setDefaultEmailTriggers** `boolean`

Seed the default email triggers when enabling the email service.

**requireAutoOrgUser** `boolean`

Require auto‑creation of the organization user.

**enablePrivateComments** `boolean`

Initial value for the workspace‑scoped private comments feature flag. Defaults to `false` when omitted.

**emailServiceConfig** `object`

Configuration object for the email service. See [Update Email Config](https://velt.dev/docs/api-reference/rest-apis/v2/workspace/emailconfig-update.md) for the full schema.

**properties**

**type** `string`

Email service provider type. Accepted values: `"default"` or `"sendgrid"`.

**apiKey** `string`

API key for the email service provider (e.g., your SendGrid API key).

**fromEmail** `string`

Sender email address.

**fromCompany** `string`

Sender company name.

**commentTemplateId** `string`

SendGrid template ID for comment notification emails.

**tagTemplateId** `string`

SendGrid template ID for tag/mention notification emails.

**webhookServiceConfig** `object`

Configuration object for the webhook service. See [Update Webhook Config](https://velt.dev/docs/api-reference/rest-apis/v2/workspace/webhookconfig-update.md) for the full schema.

**properties**

**authToken** `string`

Auth token sent with each webhook request for verification.

**rawNotificationUrl** `string`

URL to receive raw (unprocessed) webhook notifications.

**processedNotificationUrl** `string`

URL to receive processed webhook notifications.

# Example Request

#### Testing key

```JSON theme={null}
{
  "data": {
    "ownerEmail": "owner@example.com",
    "type": "testing",
    "createAuthToken": true
  }
}
```

#### Production key (default North America region)

```JSON theme={null}
{
  "data": {
    "ownerEmail": "owner@example.com",
    "type": "production",
    "apiKeyName": "Production Key",
    "createAuthToken": true
  }
}
```

#### Production key with region selection (Europe)

```JSON theme={null}
{
  "data": {
    "ownerEmail": "owner@example.com",
    "type": "production",
    "apiKeyName": "EU Production Key",
    "persistenceDBRegion": "eur3",
    "realtimeDBRegion": "europe-west1",
    "createAuthToken": true
  }
}
```

# Example Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "API key created successfully.",
    "data": {
      "apiKey": "your_new_api_key"
    }
  }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "message": "ownerEmail is required."
  }
}
```

# Errors

| Status | When |
| - | - |
| `INVALID_ARGUMENT` | Missing/invalid `ownerEmail` or `type`, or an unsupported `persistenceDBRegion` / `realtimeDBRegion` (including an explicit empty string). |
| `PERMISSION_DENIED` | Invalid workspace credentials, or the workspace is not allowed to create production API keys. |
| `FAILED_PRECONDITION` | Creating a production key but the workspace has not been upgraded to a paid plan. |
| `RESOURCE_EXHAUSTED` | The workspace has reached its maximum number of production API keys. |

```js theme={null}
{
  "result": {
    "status": "success",
    "message": "API key created successfully.",
    "data": {
      "apiKey": "your_new_api_key"
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.