Skip to main content
Every Arcmira v1 endpoint except /v1/health and /v1/openapi.json requires authentication. Pass your key in either of two equivalent headers:
Bearer token (preferred)
Authorization: Bearer arc_sk_your_key
API key header
x-api-key: arc_sk_your_key
The two forms are interchangeable. If both headers are sent, x-api-key wins.

​
Key format

Arcmira keys start with the arc_sk_ prefix and contain 64 hex characters after it. The dashboard only displays the prefix and last 4 characters after creation. The raw secret is shown once, at creation time. 
arc_sk_a1b2c3d4...xxxx

​
Creating keys

  1. Go to Dashboard → API Keys.
  2. Click Create key, give it a descriptive name (e.g. production-backend), and select scopes.
  3. Copy the revealed secret immediately and store it in your secrets manager.
  4. Use Disable to temporarily revoke a key without deleting it. Deleting is permanent.
Key secrets are shown once, at creation time. You can edit scopes later, but rotate the key if the secret may have been exposed.

​
Storage hygiene

  • Keys are server-side credentials. Do not ship them to browsers, mobile clients, or any environment you don’t control.
  • Rotate keys when team members leave or when one might have been exposed.
  • Each key tracks last_used_at and last_used_ip so you can spot dormant or suspicious keys.
  • Calls against disabled, expired, or revoked keys return 401 invalid_api_key.
  • Mint one key per environment and per process. Don’t reuse production keys in CI. Each key has its own rate-limit bucket, usage trail, and Community Review reputation.

​
The scopes

Every key carries read plus any explicit permissions you grant. Endpoints that require a scope you don’t have return 403 insufficient_scope; the message names the missing scope.
ScopeTier requiredRequired for
readAnyAll read endpoints (search, entities, mentions, appearances, alert history). Granted automatically on every key; cannot be removed.
monitors:writeAny paidPOST / PATCH / DELETE on /v1/monitors*, including monitor tracker mutations.
trackers:writeAny paidPOST / PATCH / DELETE on /v1/trackers*.
recommendations:readPro+GET /v1/recommendations, GET /v1/entities/{id}/recommendations, GET /v1/channels/{id}/sponsors, GET /v1/mentions?details=full, and the recommendations_summary blocks on entity and channel reads.
Commercial intelligence access is premium because it parses creator ad reads, sponsors, and endorsements at scale. It requires both a Pro+ tier (pro_plus, ultra, teams, enterprise) and recommendations:read. On lower tiers, commercial routes return 403 recommendations_not_enabled regardless of scope. See Commercial intelligence or check your plan from Pricing.

​
Choosing scopes

  • Read-only integrations (analytics, dashboards, BI exports): mint a key with read only. That key cannot create or delete anything.
  • Automation that creates trackers (CRM enrichment, monitor sync, GTM signals): needs trackers:write, and monitors:write if it also manages monitors.
  • Commercial intelligence integrations (advertiser dashboards, sponsor research, ad-spend modeling): need recommendations:read on a Pro+ plan. On Pro+ plans the dashboard selects it by default for new keys.

​
Verifying a key

The fastest sanity check is /v1/me: 
const res = await fetch('https://api.arcmira.com/v1/me', {
  headers: { Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}` },
});
const me = await res.json();

import os, httpx

me = httpx.get(
    'https://api.arcmira.com/v1/me',
    headers={'Authorization': f"Bearer {os.environ['ARCMIRA_API_KEY']}"},
).json()

curl https://api.arcmira.com/v1/me \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"
Response
{
  "user_id": "usr_...",
  "tier": "pro_plus",
  "scopes": ["read", "monitors:write", "recommendations:read"],
  "rate_limit": 240,
  "recommendations_api_enabled": true,
  "usage": {
    "rows_used": 1234,
    "rows_remaining": 98766,
    "monthly_rows": 100000,
    "current_spend_cents": 0
  }
}
  • recommendations_api_enabled is the tier-level gate: true only on Pro+ tiers, independent of scopes. If it’s false, commercial routes will 403 even with the scope attached.
  • usage shows the row budget; check it before metered pulls. /v1/me costs 0 rows, though like every authenticated route it returns 402 quota_exceeded once your pool is exhausted with on-demand disabled.

​
Error shape on insufficient scope

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "API key requires monitors:write.",
    "doc_url": "https://docs.arcmira.com/errors#insufficient_scope",
    "request_id": "req_..."
  }
}
The fix is to edit the key or mint a new key with the right scopes from Dashboard → API Keys. For commercial scopes you also need a Pro+ plan.