[{"data":1,"prerenderedAt":103},["ShallowReactive",2],{"doc:\u002Fgetting-started\u002Fauthentication":3},{"page":4,"toc":97},{"path":5,"title":6,"description":7,"blocks":8},"\u002Fgetting-started\u002Fauthentication","Authentication","How to pass your API key to the REST API and signed database download endpoints.",[9,12,17,19,35,39,42,44,61,64,67,70,76,79],{"type":10,"text":11},"p","API keys are created and managed in the [dashboard](https:\u002F\u002Fdashboard.ipscope.io). Live keys start with `ips_live_` so secret scanners in GitHub and CI pipelines can detect accidental commits immediately.",{"type":13,"level":14,"text":15,"id":16},"heading",2,"Three ways to send a key","three-ways-to-send-a-key",{"type":10,"text":18},"Send the key in the `Authorization` header, the `X-API-Key` header, or the `key` query parameter. All three are accepted on every authenticated endpoint.",{"type":20,"samples":21},"code",[22,27,31],{"label":23,"lang":24,"code":25,"html":26},"Authorization header (recommended)","bash","curl -sS https:\u002F\u002Fapi.ipscope.io\u002Fv1\u002Fip\u002F198.51.100.7 \\\n  -H \"Authorization: Bearer ips_live_••••••••\"","\u003Cpre class=\"shiki ipscope\" style=\"background-color:var(--shiki-background);color:var(--shiki-foreground)\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-token-function)\">curl\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string)\"> -sS\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string)\"> https:\u002F\u002Fapi.ipscope.io\u002Fv1\u002Fip\u002F198.51.100.7\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-token-string)\">  -H\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string-expression)\"> \"Authorization: Bearer ips_live_••••••••\"\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",{"label":28,"lang":24,"code":29,"html":30},"X-API-Key header","curl -sS https:\u002F\u002Fapi.ipscope.io\u002Fv1\u002Fip\u002F198.51.100.7 \\\n  -H \"X-API-Key: ips_live_••••••••\"","\u003Cpre class=\"shiki ipscope\" style=\"background-color:var(--shiki-background);color:var(--shiki-foreground)\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-token-function)\">curl\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string)\"> -sS\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string)\"> https:\u002F\u002Fapi.ipscope.io\u002Fv1\u002Fip\u002F198.51.100.7\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-token-string)\">  -H\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string-expression)\"> \"X-API-Key: ips_live_••••••••\"\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",{"label":32,"lang":24,"code":33,"html":34},"Query parameter","curl -sS \"https:\u002F\u002Fapi.ipscope.io\u002Fv1\u002Fip\u002F198.51.100.7?key=ips_live_••••••••\"","\u003Cpre class=\"shiki ipscope\" style=\"background-color:var(--shiki-background);color:var(--shiki-foreground)\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-token-function)\">curl\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string)\"> -sS\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string-expression)\"> \"https:\u002F\u002Fapi.ipscope.io\u002Fv1\u002Fip\u002F198.51.100.7?key=ips_live_••••••••\"\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",{"type":36,"tone":37,"text":38},"callout","tip","Prefer `Authorization: Bearer` or `X-API-Key` in production. Query parameters are often recorded in proxy access logs and APM traces.",{"type":13,"level":14,"text":40,"id":41},"Using keys with Official Server SDKs","using-keys-with-official-server-sdks",{"type":10,"text":43},"All 8 [official server SDKs](\u002Fsdks) accept an explicit `apiKey` \u002F `api_key` parameter and automatically send `Authorization: Bearer` and `X-API-Key` headers on every request:",{"type":20,"samples":45},[46,51,56],{"label":47,"lang":48,"code":49,"html":50},"Python","python","from ipscope import AsyncIpScopeClient\n\nclient = AsyncIpScopeClient(api_key=os.environ[\"IPSCOPE_KEY\"])","\u003Cpre class=\"shiki ipscope\" style=\"background-color:var(--shiki-background);color:var(--shiki-foreground)\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-token-keyword)\">from\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\"> ipscope \u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-keyword)\">import\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\"> AsyncIpScopeClient\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-foreground)\">client \u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-keyword)\">=\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-function)\"> AsyncIpScopeClient\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-punctuation)\">(api_key\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-keyword)\">=\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-punctuation)\">os.environ[\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string-expression)\">\"IPSCOPE_KEY\"\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-punctuation)\">])\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",{"label":52,"lang":53,"code":54,"html":55},"Node.js","ts","import { IpScopeClient } from '@ipscope\u002Fsdk-node';\n\nconst client = new IpScopeClient({ apiKey: process.env.IPSCOPE_KEY });","\u003Cpre class=\"shiki ipscope\" style=\"background-color:var(--shiki-background);color:var(--shiki-foreground)\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-token-keyword)\">import\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\"> { IpScopeClient } \u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-keyword)\">from\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string-expression)\"> '@ipscope\u002Fsdk-node'\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\">;\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-token-keyword)\">const\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-constant)\"> client\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-keyword)\"> =\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-keyword)\"> new\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-function)\"> IpScopeClient\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\">({ apiKey\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-keyword)\">:\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-constant)\"> process\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\">.\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-constant)\">env\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\">.\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-constant)\">IPSCOPE_KEY\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\"> });\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",{"label":57,"lang":58,"code":59,"html":60},"Go","go","client := ipscope.NewClient(ipscope.Config{APIKey: os.Getenv(\"IPSCOPE_KEY\")})","\u003Cpre class=\"shiki ipscope\" style=\"background-color:var(--shiki-background);color:var(--shiki-foreground)\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:var(--shiki-foreground)\">client \u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-keyword)\">:=\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\"> ipscope.\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-function)\">NewClient\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\">(\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-function)\">ipscope\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\">.\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-function)\">Config\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\">{APIKey: os.\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-function)\">Getenv\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\">(\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-token-string-expression)\">\"IPSCOPE_KEY\"\u003C\u002Fspan>\u003Cspan style=\"color:var(--shiki-foreground)\">)})\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",{"type":13,"level":14,"text":62,"id":63},"Keeping keys on the server","keeping-keys-on-the-server",{"type":36,"tone":65,"text":66},"warning","API keys are designed for server-side backends, edge workers and cron jobs. Do not embed a live API key in browser JavaScript or mobile binaries.",{"type":13,"level":14,"text":68,"id":69},"Rotating a key without downtime","rotating-a-key-without-downtime",{"type":71,"items":72},"list",[73,74,75],"Create a second key in the dashboard (`Settings → API Keys`).","Deploy the new key to your servers and verify traffic in the usage graph.","Revoke the old key. Revocation takes effect globally within 30 seconds.",{"type":13,"level":14,"text":77,"id":78},"When authentication fails","when-authentication-fails",{"type":80,"columns":81,"rows":85},"table",[82,83,84],"Status","Code","Cause",[86,90,93],[87,88,89],"`401`","`missing_api_key`","No key was sent on an endpoint that requires authentication.",[87,91,92],"`invalid_api_key`","The key does not exist or has been revoked.",[94,95,96],"`403`","`forbidden_field_family`","The request asked for a field family outside the key’s plan tier.",[98,99,100,101,102],{"id":16,"text":15,"level":14},{"id":41,"text":40,"level":14},{"id":63,"text":62,"level":14},{"id":69,"text":68,"level":14},{"id":78,"text":77,"level":14},1793226504196]