Skip to content
AM

API keys

InBlack has two API-key families with different scopes and lifecycles. Do not interchange them.

Tenant API keys

The Accounting GraphQL API manages legacy tenant keys. They begin with ldk_, identify one tenant, and store a list of Accounting Permission values.

mutation CreateTenantKey($input: CreateAPIKeyInput!) {
  createAPIKey(input: $input)
}

CreateAPIKeyInput accepts name and permissions. Current permission values include VIEW_REPORTS, VIEW_ENTRIES, CREATE_ENTRIES, POST_ENTRIES, MANAGE_ACCOUNTS, MANAGE_STRIPE, MANAGE_TEAM, MANAGE_SETTINGS, MANAGE_BILLING, EXPORT_DATA, and AGENT_EXECUTE.

The mutation returns the plaintext key string once. The database stores a bcrypt hash and lookup prefix. apiKeys lists active key metadata without plaintext, and revokeAPIKey(id) soft-revokes a key. All three operations require authentication and MANAGE_SETTINGS; creation also enforces the tenant API-key quota.

Send a tenant key as a bearer credential. Validation resolves the tenant from the key itself, so an additional tenant header cannot move it to another tenant.

The authorization matcher also accepts structured product/module/action strings for keys provisioned through compatible internal paths, but the public Accounting CreateAPIKeyInput exposes the fixed Permission enum rather than arbitrary scope strings.

Studio and Storefront keys

Studio manages site-scoped keys through its GraphQL API:

  • apiKeys(siteId) lists metadata.
  • createApiKey(input) returns metadata plus plaintext.
  • rotateApiKey(input) creates a replacement and returns its plaintext.
  • revokeApiKey(siteId, id) revokes one key.

These keys have a type (PUBLISHABLE or SECRET), environment (TEST or LIVE), and scope (READ_ONLY, READ_WRITE, or ADMIN). Publishable keys are the browser-safe credential used by the Storefront SDK. See SDK key auth.

Studio key management requires a human owner or admin. Creation is limited to 10 keys per hour by default and also enforces the tenant plan quota. Rotation supports an optional grace period up to 30 days and records create, rotate, and revoke events in AuditCore.

The current MCP catalog can list, rotate, and revoke Studio API keys. It does not expose a create-key tool, which keeps first-time plaintext creation in an authenticated product API/UI flow.

Security rules

  • Store plaintext only in a secrets manager or secure server session.
  • Never log or commit a full key.
  • Use a publishable key, not a secret key, in browser code.
  • Rotate or revoke immediately after suspected exposure.
  • Treat the returned plaintext as non-recoverable; list operations expose only metadata and prefixes.

API keys are for customer integrations. InBlack service-to-service calls use service tokens, and interactive users use OAuth bearer tokens.