Compass DocsBy Mesa
Open App

⚡ Your First Request

The identity endpoint is the simplest call in the API. It tells you which account a key belongs to, its plan, and its live credit balance. It is the right way to confirm a key works before you build on it, and it is free.

The request

curl https://compass.mesa.so/api/v1/me \
  -H "Authorization: Bearer ck_live_your_key_here"

The response

{
  "apiVersion": "1.1.1",
  "id": "clx0...",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "tier": "starter",
  "organization": "Example Labs",
  "creditsBalance": 2850,
  "apiKey": {
    "label": "agent",
    "prefix": "ck_live_AbCdEf",
    "scopes": ["read:metadata", "read:contacts"],
    "environment": "live"
  },
  "pricing": {
    "currency": "credits",
    "basicCallCredits": 5,
    "privateCallCredits": 10,
    "note": "Data calls cost 5 credits. Revealing a contact's private channels costs 10 the first time, then 5."
  },
  "meta": { "creditsCharged": 0, "creditsBalance": 2850 }
}

What the fields mean

  • apiVersion is the API build you are talking to, also sent as the Compass-API-Version response header.
  • id, name, email identify the account the key belongs to.
  • tier is the plan: free, starter, pro, team, or enterprise.
  • organization is your workspace name, or Compass if none is set.
  • creditsBalance is how many credits you have right now.
  • apiKey echoes the key you used: its label, display prefix, scopes, and environment.
  • pricing states the credit cost of a basic call and a private reveal.
  • meta reports what this call charged (0 for /v1/me) and your balance after it.

What comes next

/v1/me is free. Your next call, a data or search call, costs 5 credits (a private contact reveal costs 10). If creditsBalance is 0, fund the account first: see Pricing & Quotas. A call made with too few credits returns 402 Payment Required and charges nothing.

If it fails

A 401 means the key is missing, malformed, or revoked. Check that the header reads exactly Authorization: Bearer ck_live_… and that the key is still active in your API tab. See Errors & Status Codes.