Authentication

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

API Key Format

Authorization: Bearer ak_live_your_key_here

Key Types

Prefix	Type	Created By	Purpose
`ak_live_`	sync	User	Partner data sync — push artworks, artists, events
`ak_search_`	search	Admin	Third-party read-only data access

Getting an API Key

Log in to your Artland account
Navigate to Account → API Keys (/account/api-keys)
Click Generate New Key
Give it a label (e.g., “Gallery CMS Sync”)
Copy the key — it’s shown once

Access Tiers

Your tier depends on your Artland subscription status:

User Status	Key Tier	Scopes	Rate Limit	Daily Reads
`claimed`	`read_only`	`*:read`, `search:read`	30/min	500/day
`subscriber`	`read_write`	`:read`, `:write`, `search:read`	100/min	Unlimited
`sponsored`	`read_write`	`:read`, `:write`, `search:read`	100/min	Unlimited
`paused`	Blocked	—	—	—

Scopes

Scopes control what operations your key can perform:

Scope	Description
`artworks:read`	List and view artworks
`artworks:write`	Create and update artworks
`artists:read`	List and view artists
`artists:write`	Create and update artists (gallery keys only)
`events:read`	List and view events
`events:write`	Create, update, and delete events
`profile:read`	View your entity profile
`profile:write`	Update your entity profile
`search:read`	Search across all entities

Verifying Your Key

Use the /v1/me endpoint to check your key’s identity, scopes, and usage:

curl https://api.artland.com/v1/me \
  -H "Authorization: Bearer ak_live_your_key_here"

Response:

{
  "key_prefix": "ak_live_a1b2",
  "label": "Gallery CMS Sync",
  "tier": "read_write",
  "scopes": ["artworks:write", "artists:write", "events:write", "profile:read"],
  "entity": { "type": "gallery", "id": 1, "name": "Gagosian" },
  "usage": { "reads_today": 12, "writes_today": 5, "daily_read_limit": null }
}

Error Responses

Code	Meaning
`401`	Missing or invalid API key
`403`	Insufficient scope or paused account
`429`	Rate limit exceeded

See Errors for full details.