Authentication - TeamBattles

API Keys

All API requests require authentication via an API key passed as a Bearer token in the Authorization header.

curl -H "Authorization: Bearer tb_your_api_key_here" \
  https://teambattles.gg/api/v1/matches

Copy your API key immediately after creation. It cannot be retrieved later. If you lose it, you must create a new one.

Each API key has granular permissions across four categories:

Category	Scope	Values	Description
Matches	`user_matches`	none, read	Access your match history
Matches	`team_matches`	none, read	Access team match history
Matches	`org_matches`	none, read	Access organization match history
Connections	`discord`, `twitch`, `github`, `battlenet`	none, enabled	Access linked platform data
Game	`scores`	none, write	Submit scores via API
Game	`lifecycle`	none, read, read-write	Query/manage match lifecycle
Webhooks	`manage`	none, enabled	Create and manage webhook endpoints

Game API permissions (scores, lifecycle) are only available to approved Game Developers. Webhook management requires General Developer access.

API keys start with tb_ followed by a random string. When viewing your keys in the dashboard, only the prefix is shown for security.

Authentication and API errors return standard HTTP status codes with a consistent format:

{
	"error": "error_code",
	"details": "Additional information (optional)"
}

Code	HTTP Status	Description
`error_api_key_required`	401	No API key provided in Authorization header
`error_api_key_invalid`	401	API key is invalid or revoked
`error_api_key_permission_denied`	403	API key lacks required permission
`error_team_membership_required`	403	User is not an active member of the team
`error_org_membership_required`	403	User is not an active member of the organization
`error_team_not_found`	404	Team ID or slug not found
`error_org_not_found`	404	Organization ID or slug not found
`error_invalid_request`	400	Request body or parameters are invalid
`error_invalid_cursor`	400	Pagination cursor is invalid or expired
`error_invalid_limit`	400	Limit must be between 1 and 100
`error_invalid_date_format`	400	Date parameter is not valid ISO 8601
`error_internal`	500	Internal server error