Headless signup (API-only path)

curl --request POST \
  --url https://api.gigstack.io/v2/auth/signup \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Internal-API-Key: <api-key>' \
  --data '
{
  "email": "agent@example.com",
  "name": "Agent Builder Inc",
  "plan_id": "agent-tier",
  "rfc": "XAXX010101000",
  "country": "MEX",
  "billing_cycle": "monthly",
  "stripe_payment_method": "pm_1Q...",
  "livemode": true,
  "partner_ref": "SANTIAGO-A7K9",
  "metadata": {
    "source": "my-agent-cli"
  }
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Internal-API-Key': '<api-key>',
    'Idempotency-Key': '<idempotency-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'agent@example.com',
    name: 'Agent Builder Inc',
    plan_id: 'agent-tier',
    rfc: 'XAXX010101000',
    country: 'MEX',
    billing_cycle: 'monthly',
    stripe_payment_method: 'pm_1Q...',
    livemode: true,
    partner_ref: 'SANTIAGO-A7K9',
    metadata: {source: 'my-agent-cli'}
  })
};

fetch('https://api.gigstack.io/v2/auth/signup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/auth/signup"

payload = {
    "email": "agent@example.com",
    "name": "Agent Builder Inc",
    "plan_id": "agent-tier",
    "rfc": "XAXX010101000",
    "country": "MEX",
    "billing_cycle": "monthly",
    "stripe_payment_method": "pm_1Q...",
    "livemode": True,
    "partner_ref": "SANTIAGO-A7K9",
    "metadata": { "source": "my-agent-cli" }
}
headers = {
    "X-Internal-API-Key": "<api-key>",
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "user_id": "aJGZiWGWQGfZEZk9XbtShj3pxBx2",
  "team_id": "team_xxx",
  "billing_account_id": "ba_xxx",
  "subscription": {
    "id": "sub_1Q...",
    "status": "active",
    "current_period_end": 1740000000
  },
  "api_keys": {
    "live": "eyJhbGciOi...",
    "test": "eyJhbGciOi..."
  },
  "next_steps": {
    "fiel_upload_url": "POST /v2/teams/{team_id}/sat-connection",
    "manifest_sign_url": "POST /v2/teams/{team_id}/manifest/sign",
    "note": "RFC and FIEL only required for CFDI invoicing. Clients, payments, services, receipts, and webhooks all work without them."
  }
}

Auth

Headless signup (API-only path)

Create a complete gigstack account end-to-end without the alphav2 web UI. Designed for AI agents and partner integrations: a single call provisions a Firebase Auth user, billing account, team, plan subscription, and returns live + test API keys.

Auth: This endpoint authenticates with X-Internal-API-Key (partner-issued), NOT a normal Authorization: Bearer API token. Bearer tokens are scoped to a team — a brand-new caller has none yet.

Idempotency: Idempotency-Key header (UUID v4) is required. Retries with the same key return the cached response and never re-create resources.

Plan paths:

plan_id: "free" — direct Firestore write, no Stripe, instant activation.
Any paid plan — uses stripe.subscriptions.create with the supplied PaymentMethod token (off-session). No Checkout redirect. billingAccount.haveAPIAccess is set synchronously so the API gate passes on the first call.

RFC and FIEL: not required at signup. Defaults to RFC genérico (XAXX010101000). Customers can later upload their own via POST /v2/teams/{team_id}/sat-connection. Clients, payments, services, receipts, and webhooks all work without FIEL.

API keys: returned in the response body once — not retrievable later. The caller must store them immediately.

POST

auth

signup

Headless signup (API-only path)

curl --request POST \
  --url https://api.gigstack.io/v2/auth/signup \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Internal-API-Key: <api-key>' \
  --data '
{
  "email": "agent@example.com",
  "name": "Agent Builder Inc",
  "plan_id": "agent-tier",
  "rfc": "XAXX010101000",
  "country": "MEX",
  "billing_cycle": "monthly",
  "stripe_payment_method": "pm_1Q...",
  "livemode": true,
  "partner_ref": "SANTIAGO-A7K9",
  "metadata": {
    "source": "my-agent-cli"
  }
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Internal-API-Key': '<api-key>',
    'Idempotency-Key': '<idempotency-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'agent@example.com',
    name: 'Agent Builder Inc',
    plan_id: 'agent-tier',
    rfc: 'XAXX010101000',
    country: 'MEX',
    billing_cycle: 'monthly',
    stripe_payment_method: 'pm_1Q...',
    livemode: true,
    partner_ref: 'SANTIAGO-A7K9',
    metadata: {source: 'my-agent-cli'}
  })
};

fetch('https://api.gigstack.io/v2/auth/signup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/auth/signup"

payload = {
    "email": "agent@example.com",
    "name": "Agent Builder Inc",
    "plan_id": "agent-tier",
    "rfc": "XAXX010101000",
    "country": "MEX",
    "billing_cycle": "monthly",
    "stripe_payment_method": "pm_1Q...",
    "livemode": True,
    "partner_ref": "SANTIAGO-A7K9",
    "metadata": { "source": "my-agent-cli" }
}
headers = {
    "X-Internal-API-Key": "<api-key>",
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "user_id": "aJGZiWGWQGfZEZk9XbtShj3pxBx2",
  "team_id": "team_xxx",
  "billing_account_id": "ba_xxx",
  "subscription": {
    "id": "sub_1Q...",
    "status": "active",
    "current_period_end": 1740000000
  },
  "api_keys": {
    "live": "eyJhbGciOi...",
    "test": "eyJhbGciOi..."
  },
  "next_steps": {
    "fiel_upload_url": "POST /v2/teams/{team_id}/sat-connection",
    "manifest_sign_url": "POST /v2/teams/{team_id}/manifest/sign",
    "note": "RFC and FIEL only required for CFDI invoicing. Clients, payments, services, receipts, and webhooks all work without them."
  }
}

Authorizations

X-Internal-API-Key

string

header

required

Internal provisioning key used only by POST /v2/auth/signup, which creates brand-new accounts and therefore cannot present a tenant Bearer token.

The header X-Signup-Api-Key is accepted as an alias when X-Internal-API-Key is absent. This credential is issued to internal gigstack systems and is not part of the public tenant API surface.

Headers

X-Internal-API-Key

string

required

Internal provisioning key, constant-time validated. This is the credential the signupApiKey security scheme refers to; X-Signup-Api-Key is accepted as an alias when this header is absent. A Bearer token is not used here.

Idempotency-Key

string<uuid>

required

UUID v4. Required so retries are safe.

Body

application/json

string<email>

required

Example:

"agent@example.com"

name

string

required

Used for displayName + legal_name placeholder.

Example:

"Agent Builder Inc"

plan_id

string

required

A plan id from the subscriptionPricing collection. Use "free" for the free tier or "agent-tier" for the API-only paid plan.

Example:

"agent-tier"

rfc

string

Optional. Defaults to RFC genérico if omitted.

Example:

"XAXX010101000"

country

string

default:MEX

Example:

"MEX"

billing_cycle

enum<string>

Ignored for free plans.

Available options:

monthly,

annual

Example:

"monthly"

stripe_payment_method

string

Required for paid plans only. Created client-side via Stripe.js.

Example:

"pm_1Q..."

livemode

boolean

default:true

partner_ref

string

Optional partner referral code. Captured for future commission routing (not yet wired to Stripe Connect transfer_data).

Example:

"SANTIAGO-A7K9"

metadata

object

Show child attributes

Example:

{ "source": "my-agent-cli" }

Response

Account created successfully

user_id

string

team_id

string

billing_account_id

string

subscription

object | null

Show child attributes

api_keys

object

Show child attributes

next_steps

object

Show child attributes

Clients

Services

Descarga Masiva SAT

Invoices

Payments

Receipts

Retentions

Teams

Users

Webhooks

Catalogs

Auth

SAT Lists

Documents

Platform Payouts

Headless signup (API-only path)

Authorizations

Headers

Body

Response