Skip to content
Fotobots Partner Docs

Authentication & API Keys

The .fotobots.dev addresses on this page are staging examples. Use the URL and API key for your own environment.

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: api.fotobots.dev
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.