Skip to content
Fotobots Partner Docs

Authentication & API Keys

All partner endpoints on Fotobots require an Organization API Key transmitted via an HTTP header.

In-Docs Interactive PlaygroundSANDBOX

Sign in directly on this documentation site to auto-inject your Sandbox API Key into all examples and the API Explorer.

Header Requirement

Include your API Key in the x-api-key header with every request:

POST /openapi/albums/list HTTP/1.1
Host: sandbox-api.fotobots.run
Content-Type: application/json
x-api-key: fb_test_YOUR_KEY

[!CAUTION] Keep Your API Keys Secret: Never commit API keys to public repositories or expose production keys in client-side mobile/web code. All production API calls should be proxied through your backend server.

Key Types

Key PrefixEnvironmentPurposeCredit Usage
fb_test_...SandboxIntegration testing, local development, staging verification.Free Mock Credits
fb_live_...ProductionLive marathon events, official runner search platforms.Deducts Real Credits

Key Scopes & Permissions

When creating an API Key in the Web Admin, you can select granular permissions:

  • search:read: Allows querying runner faces and bib numbers. Ideal for frontend timing search apps.
  • photo:upload: Allows generating presigned upload URLs and triggering indexing. Ideal for photographer upload stations.
  • album:manage: Allows creating and editing race albums.

👉 See the Web Admin API Keys Guide for screenshots on how to generate keys.