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

# Authentication and test mode

> Choose the right key and team before making requests.

Create an API key in [gigstack settings](https://app.gigstack.pro/settings?tab=api).
Send the literal `Bearer ` prefix followed by the key:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Keep keys on your server. Do not put them in browser JavaScript, public repositories,
screenshots, or prompts shared with other people.

A standard API key also requires API access on the team’s billing account, including in test
mode. A `403` message beginning `La API se encuentra disponible para un plan más grande`
means the account lacks API access; generating another key does not fix that. Ask the
account owner to check the plan. A different message, `Tu plan no incluye múltiples
cuentas emisoras`, means the requested cross-team operation lacks the
`multipleIssuerAccounts` feature. See [authentication errors](/guides/welcome#authentication-errors)
to distinguish these from an invalid or revoked key.

## Environments

| Environment | Base URL | Key |
| - | - | - |
| Public API | `https://api.gigstack.io/v2` | Standard live or test API key |
| Internal staging | `https://gigstack-staging-9z9nnaat.uc.gateway.dev/v2` | Key created in staging |

Staging is a separate deployment and data store. `livemode: false` is a data mode within
an environment, not a staging hostname. A staging key was verified against the staging
gateway; the public API rejected that same key with `403 API Key inválida`.

## Live and test data

Both modes use `https://api.gigstack.io/v2`. The key determines the mode; a request-body
`livemode` field does not turn a live API key into a test key.

Lists and searches return data for the key's mode. Operations across modes can be rejected.
For draft stamping, check the **stored draft’s** `livemode`: the handler stamps in the
draft’s mode. Start with a draft created by your test key; do not use an existing live draft.

Some operations, including creating teams and running end-of-month invoicing, require live keys.
See [API fundamentals](/guides/welcome#test-mode) for the current limitations.

Test mode also does not disable every notification workflow. Before creating test
records, confirm the account’s notification recipients and webhook destinations.
Invoice email flags and payment automation flags are not universal switches; see the
[invoice test instructions](/recipes/invoice) and
[refund automation checks](/recipes/refund#before-testing-check-refund-automations).

## Working with multiple teams

A gigstack Connect master team can use `?team=TEAM_ID` for eligible teams sharing its billing
account. This requires the `multipleIssuerAccounts` feature. OAuth access tokens are bound
to one team and cannot use this parameter to switch teams.

User-scoped MCP tokens use current team membership and are exempt from these API-access
and multiple-issuer plan gates. With an MCP token, send an explicit `?team=TEAM_ID`
for the team you intend to operate on; membership is still checked. The record-only
[refund test](/verification#additional-record-only-refund-check) used this token type.

Follow [gigstack Connect](/guides/gigstack-connect) for setup and errors.

## Authentication errors

Authentication failures can return a plain `{message, error, error_description}` object,
rather than the standard API error envelope. Check the HTTP status first and preserve the
response body when diagnosing a failed call.

Account signup has a separate authentication mechanism. See its API reference entry;
a regular bearer key does not replace the internal signup credential.


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