> ## Documentation Index > Fetch the complete documentation index at: https://docs.mareaalcalina.com/llms.txt > Use this file to discover all available pages before exploring further. # Bootstrap user > Use this when an agent wants to create a Marea account on behalf of a user with one round-trip (account + storefront + verification email). Creates a Firebase Auth user + Firestore user doc + restricted user key + (optionally) a starter storefront via createMenuCore + sends a 6-digit verification email. Returns 201 (or 207 if the storefront manifest exceeded plan limits). The userKey is returned ONCE — store it. ## OpenAPI ````yaml /openapi.json post /v1/users openapi: 3.1.0 info: title: Marea Alcalina API version: 1.0.0 description: >- Operations + retention API for small-business commerce. Bootstrap a digital menu (food) or product catalog (retail/services) plus a public hosted storefront for a single operator; orders flow through WhatsApp, web checkout, or in-person — channel is per-storefront config. **Auth**: `Authorization: Bearer mk__...` **Free tier**: 1 storefront, 30 products, no publish. **Errors**: every non-2xx response uses the §9.6 envelope, including a `nextActions[]` array. Surface those verbatim to your user. **Rate limits**: every response carries `X-RateLimit-*` headers. 429s carry `Retry-After`. **Idempotency**: state-mutating endpoints accept an optional `Idempotency-Key` request header; replays within 24h return the original response. contact: name: Marea Alcalina API support url: https://developers.mareaalcalina.com email: developers@mareaalcalina.com termsOfService: https://mareaalcalina.com/terms license: name: Proprietary url: https://mareaalcalina.com/terms x-generated-at: '2026-05-15T19:15:00Z' servers: - url: https://api.mareaalcalina.com description: Production - url: https://api-staging.mareaalcalina.com description: Staging security: - BearerAuth: [] - ApiKeyHeader: [] tags: - name: Identity description: Inspect the calling key (user or developer). - name: Users description: Bootstrap, verify, and inspect users created by a developer key. - name: Storefronts description: Create, update, and publish hosted storefronts. - name: Products description: Add and update products inside a storefront. - name: Webhooks description: Register the developer-key destination URL for user-lifecycle events. paths: /v1/users: post: tags: - Users summary: Bootstrap user description: >- Use this when an agent wants to create a Marea account on behalf of a user with one round-trip (account + storefront + verification email). Creates a Firebase Auth user + Firestore user doc + restricted user key + (optionally) a starter storefront via createMenuCore + sends a 6-digit verification email. Returns 201 (or 207 if the storefront manifest exceeded plan limits). The userKey is returned ONCE — store it. operationId: bootstrapUser parameters: - name: Idempotency-Key in: header required: false description: >- Optional client-supplied key. Replays of the same key within 24h return the original response. Recommended for POSTs that mutate billing/inventory. schema: type: string maxLength: 200 example: idem_b2a9f5b9-3e0c-4a5e-b3c2-7a4ce85a6b21 - name: Accept-Language in: header required: false description: >- BCP-47 locale tag for localized error messages (`es`, `en`, `pt`). Defaults to `es`. schema: type: string example: es-MX requestBody: description: Request body. required: true content: application/json: schema: $ref: '#/components/schemas/BootstrapInput' responses: '201': description: Resource created. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/BootstrapResponse' '207': description: >- Multi-Status — created with partial-failure `errors[]` (over plan cap). headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/BootstrapResponse' '400': description: Invalid request — Zod validation failed or body malformed. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '401': description: Auth failed — missing or invalid API key. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '402': description: Plan limit — the calling user's plan does not permit this action. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: Forbidden — key scopes do not cover this operation. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: Not found — leak-less; cross-tenant access also collapses here. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '409': description: Conflict — idempotent retry collided with a different body. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '429': description: Rate limited — too many requests. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 Retry-After: description: Seconds the client should wait before retrying. schema: type: integer example: 30 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '500': description: Internal error. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '503': description: Service unavailable — downstream Firestore/Auth degraded. headers: X-RateLimit-Limit: description: >- Per-minute rate-limit ceiling for the calling key (Stripe-compatible). schema: type: integer example: 60 X-RateLimit-Remaining: description: Remaining requests in the current per-minute window. schema: type: integer example: 59 X-RateLimit-Reset: description: >- Epoch-seconds timestamp when the per-minute window rolls over (Stripe-compatible). schema: type: integer example: 1714867260 X-Request-Id: description: Server-assigned request id. Echo back in support tickets. schema: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' security: - BearerAuth: - developer:bootstrap components: schemas: BootstrapInput: type: object properties: email: type: string format: email displayName: type: string minLength: 1 maxLength: 200 country: type: - string - 'null' pattern: ^[A-Z]{2}$ language: type: - string - 'null' enum: - es - en - pt currency: type: - string - 'null' pattern: ^[A-Z]{3}$ businessType: type: - string - 'null' sourceAgent: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9 _.-]+$ initialStorefront: allOf: - $ref: '#/components/schemas/StorefrontManifest' - type: - object - 'null' required: - email - displayName - sourceAgent BootstrapResponse: type: object properties: userId: type: string storefrontId: type: - string - 'null' userKey: type: string pattern: ^mk_user_ verificationStatus: type: string enum: - pending verificationExpiresAt: type: string format: date-time verificationDeliveryHint: type: string enum: - email-only appliedDefaults: $ref: '#/components/schemas/AppliedDefaults' idempotent: type: boolean errors: type: array items: type: object properties: type: type: string code: type: string message: type: string required: - type - code - message required: - userId - userKey - verificationStatus - verificationExpiresAt - verificationDeliveryHint - appliedDefaults ApiErrorResponse: type: object properties: error: $ref: '#/components/schemas/ApiErrorBody' required: - error description: §9.6 uniform error envelope. Every non-2xx response uses this shape. StorefrontManifest: type: object properties: name: type: string minLength: 1 maxLength: 100 language: type: string enum: - es - en - pt currency: type: string pattern: ^[A-Z]{3}$ businessType: type: string branding: $ref: '#/components/schemas/StorefrontBranding' schedule: $ref: '#/components/schemas/StorefrontSchedule' delivery: $ref: '#/components/schemas/StorefrontDelivery' pickup: type: - boolean - 'null' dineIn: type: - boolean - 'null' whatsapp: type: - string - 'null' biography: anyOf: - type: object properties: title: type: string description: type: string required: - title - description - type: string enum: - auto - type: 'null' blocks: anyOf: - type: string enum: - auto - type: array items: {} - type: 'null' categories: type: - array - 'null' items: type: object properties: name: type: string position: type: - integer - 'null' required: - name products: type: - array - 'null' items: $ref: '#/components/schemas/ProductManifest' maxItems: 100 required: - name - language - currency - businessType description: >- Agent-facing storefront input shape (RFC §6.18.1). Every field is PATCHable per §6.18.1.1. AppliedDefaults: type: object properties: language: type: string enum: - es - en - pt currency: type: string country: type: string businessType: type: string required: - language - currency - country - businessType ApiErrorBody: type: object properties: type: type: string enum: - rate_limited - invalid_request - auth - not_found - plan_limit - internal - conflict - idempotency_conflict - service_unavailable - tos_not_accepted description: High-level error category. Agents branch on this. example: auth code: type: string description: Stable machine-readable code. example: missing_authorization message: type: string description: Human-readable, localized via Accept-Language. doc: type: string description: Link to docs for this error code. param: type: - string - 'null' requestId: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 requestLogUrl: type: string recoverable: type: boolean retryAfterMs: type: - integer - 'null' nextActions: type: array items: $ref: '#/components/schemas/ApiNextAction' upgrade: $ref: '#/components/schemas/ApiErrorUpgrade' requiredScopes: type: array items: type: string heldScopes: type: array items: type: string required: - type - code - message - doc - param - requestId - requestLogUrl - recoverable - retryAfterMs - nextActions - upgrade StorefrontBranding: type: - object - 'null' properties: logoUrl: anyOf: - type: string format: uri - type: object properties: fileId: type: string required: - fileId - type: 'null' backgroundUrl: anyOf: - type: string format: uri - type: object properties: fileId: type: string required: - fileId - type: string enum: - auto - type: 'null' theme: anyOf: - type: object properties: primary: type: string secondary: type: string tertiary: type: string required: - primary - secondary - tertiary - type: object properties: preset: type: string required: - preset - type: 'null' font: type: - string - 'null' StorefrontSchedule: type: - object - 'null' properties: monday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' required: - open - close tuesday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' required: - open - close wednesday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' required: - open - close thursday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' required: - open - close friday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' required: - open - close saturday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' required: - open - close sunday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' required: - open - close StorefrontDelivery: type: - object - 'null' properties: enabled: type: boolean type: type: - string - 'null' enum: - fixed - distance fixedPrice: type: - number - 'null' minimum: 0 ranges: type: - array - 'null' items: type: object properties: fromKm: type: number minimum: 0 toKm: type: number minimum: 0 price: type: number minimum: 0 required: - fromKm - toKm - price required: - enabled ProductManifest: type: object properties: title: type: string minLength: 1 maxLength: 200 description: type: - string - 'null' price: type: number minimum: 0 salePrice: type: - number - 'null' minimum: 0 category: type: - string - 'null' subcategory: type: - string - 'null' imageUrl: type: - string - 'null' format: uri thumbnailUrl: type: - string - 'null' format: uri sku: type: - string - 'null' slug: type: - string - 'null' position: type: - integer - 'null' cartProduct: type: - boolean - 'null' hide: type: - boolean - 'null' stock: type: - integer - 'null' tags: type: - array - 'null' items: type: string extraProductsCategory: type: - array - 'null' items: $ref: '#/components/schemas/ExtraProductsCategory' required: - title - price description: >- Agent-facing product input shape. Mutability rule §6.18.1.1: every field PATCHable post-create. ApiNextAction: type: object properties: label: type: string example: Validate the JSON before retrying. method: type: - string - 'null' example: null url: type: - string - 'null' example: null required: - label - method - url description: A concrete action the agent can offer the user. ApiErrorUpgrade: type: - object - 'null' properties: currentPlan: type: string example: free requiredPlan: type: string example: pro upgradeUrl: type: string example: https://mareaalcalina.com/upgrade?planSource=api previewUrl: type: string description: Optional preview link the agent can surface. required: - currentPlan - requiredPlan - upgradeUrl ExtraProductsCategory: type: object properties: title: type: string obligatory: type: boolean multipleOption: type: boolean maxOptions: type: integer minOptions: type: integer extraProducts: type: - array - 'null' items: $ref: '#/components/schemas/ExtraProductOption' required: - title - obligatory - multipleOption - maxOptions - minOptions ExtraProductOption: type: object properties: title: type: string price: type: number minimum: 0 available: type: boolean stock: type: - integer - 'null' required: - title - price - available securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: mk_dev_* | mk_user_* description: >- Marea API key. `mk_dev_*` keys are developer-scoped (bootstrap, list users, register webhook). `mk_user_*` keys are user-scoped (manage that one user's storefronts/products). Scopes: `catalog:read`, `catalog:write`, `storefront:publish`, `me:verify`, `me:resendVerification`, `developer:bootstrap`, `developer:read`, `developer:issueUserKey`, `developer:webhooks`. ApiKeyHeader: type: apiKey in: header name: X-API-Key description: >- Alternative to `Authorization: Bearer`. Same `mk_*` value. Use only when your environment cannot send the `Authorization` header. ````