> ## Documentation Index > Fetch the complete documentation index at: https://developer.mailbeast.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an API key > Mint a new key for your workspace. The full token is returned **once**, so store it immediately. Requested scopes must be a subset of the calling key’s own scopes, and cannot include `apikeys:manage`. Requires the `apikeys:manage` scope, which no wildcard grants and which can only be created from the dashboard. ## OpenAPI ````yaml /openapi.json post /v1/api-keys openapi: 3.0.0 info: title: MailBeast Public API description: >- Task-shaped REST API for campaigns, leads, deliverability, verification and lead discovery. Authenticate with an API key (`Authorization: Bearer mb_live_…`); the workspace is resolved from the key. version: '1' contact: {} servers: - url: https://api.mailbeast.ai security: [] tags: - name: API Keys description: Create, list and revoke API keys programmatically. - name: Campaigns description: Create, configure, launch and monitor email campaigns. - name: Leads description: Add, read, update and bulk-manage a campaign’s leads. - name: Workspace description: Read usage, subscription and workspace identity. - name: Email Accounts description: >- Connect and manage the sending mailboxes your campaigns send from (SMTP/IMAP or native OAuth). - name: Analytics description: Engagement reporting – per campaign, over time, and across the workspace. - name: Lead Finder description: >- Discover new companies and leads. List past searches and poll a running search’s progress. paths: /v1/api-keys: post: tags: - API Keys summary: Create an API key description: >- Mint a new key for your workspace. The full token is returned **once**, so store it immediately. Requested scopes must be a subset of the calling key’s own scopes, and cannot include `apikeys:manage`. Requires the `apikeys:manage` scope, which no wildcard grants and which can only be created from the dashboard. operationId: apiKeys_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyDto' responses: '201': description: Key created; token returned once. content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyResponseDto' '400': description: The request body or parameters failed validation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: validation_failed message: One or more fields are invalid. status: 400 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f details: - name should not be empty '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authentication_error code: unauthenticated message: Missing or invalid API key. status: 401 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '403': description: >- The key lacks a required scope, or the plan does not include API access. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authorization_error code: permission_denied message: This API key is missing the required scope. status: 403 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '429': description: >- Rate limit exceeded - retry after the interval in the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: rate_limit_error code: rate_limited message: >- Too many requests. Retry after the interval in the Retry-After header. status: 429 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f retryAfter: 30 security: - ApiKey: [] components: schemas: CreateApiKeyDto: type: object properties: name: type: string example: CI pipeline maxLength: 120 scopes: example: - campaigns:read - usage:read description: Granted scopes (least-privilege). Must be a subset of the caller. type: array items: type: string environment: type: string enum: - live - test default: live expiresAt: type: string format: date-time description: ISO-8601 expiry; omit for a non-expiring key. required: - name - scopes CreateApiKeyResponseDto: type: object properties: token: type: string example: 'mb_live_7Fq2Ka9Lm3Xb0ZpH_Ej3VcCSRq0qZHbFbi7GQwD… ' description: The full secret token. Store it now - it is never retrievable again. apiKey: $ref: '#/components/schemas/ApiKeySummaryDto' required: - token - apiKey ApiErrorDto: type: object properties: error: $ref: '#/components/schemas/ApiErrorBodyDto' required: - error ApiKeySummaryDto: type: object properties: id: type: string format: uuid example: 5b8e1d90-3c47-4a26-9f01-7ea2c6d5b483 name: type: string example: CI pipeline keyPrefix: type: string example: mb_live_7Fq2Ka9Lm3Xb0ZpH_•••• description: Masked prefix - the full secret is only shown once, at creation. scopes: example: - campaigns:read - usage:read type: array items: type: string environment: type: string enum: - live - test example: live lastUsedAt: type: string format: date-time nullable: true expiresAt: type: string format: date-time nullable: true revokedAt: type: string format: date-time nullable: true createdAt: type: string format: date-time required: - id - name - keyPrefix - scopes - environment - lastUsedAt - expiresAt - revokedAt - createdAt ApiErrorBodyDto: type: object properties: type: type: string example: authorization_error description: Broad error class. code: type: string example: permission_denied description: Stable machine-readable code to switch on. message: type: string example: This API key is missing the required scope. status: type: number example: 403 requestId: type: string example: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f description: Correlation id - quote it in support requests. details: description: Field-level validation messages (present on validation errors). example: - name should not be empty type: array items: type: string retryAfter: type: number description: Seconds to wait before retrying (present on 429 responses). example: 30 required: - type - code - message - status - requestId securitySchemes: ApiKey: scheme: bearer bearerFormat: mb_live_… type: http ```` ## Related topics - [Quickstart](/quickstart.md) - [Revoke an API key](/api-reference/api-keys/revoke-an-api-key.md) - [List API keys](/api-reference/api-keys/list-api-keys.md) - [Create a campaign](/api-reference/campaigns/create-a-campaign.md) - [Authentication](/authentication.md)