[{"data":1,"prerenderedAt":197},["ShallowReactive",2],{"doc:\u002Freference\u002Fmanagement\u002Foverview":3},{"page":4,"toc":189,"updated":196},{"path":5,"title":6,"seoTitle":7,"description":8,"blocks":9,"examples":171},"\u002Freference\u002Fmanagement\u002Foverview","Management API","Management API: Manage Keys, Webhooks and Weights","Manage SDK keys, proxy keys, webhook endpoints and risk weights from code, with a management key, for infrastructure as code and automation.",[10,13,31,36,38,44,46,49,51,58,62,65,67,85,87,90,95,97,117,120,127,130,155,158],{"type":11,"text":12},"p","The management API does from code what **Integration** and **Smart Signals > Suspect Score** do in the dashboard: issue and revoke SDK keys and proxy keys, register webhook endpoints, and set risk weights. Use it from infrastructure-as-code tools, deployment pipelines and scripts, so a staging environment and its keys, endpoints and policy can be created the same way every time.",{"type":14,"columns":15,"rows":18},"table",[16,17],"Resource","Operations",[19,22,25,28],[20,21],"[SDK keys](\u002Freference\u002Fmanagement\u002Fsdk-keys)","List, issue, revoke, replace allowed origins",[23,24],"[Proxy keys](\u002Freference\u002Fmanagement\u002Fproxy-keys)","List, issue, revoke",[26,27],"[Webhook endpoints](\u002Freference\u002Fmanagement\u002Fwebhooks)","List, create, update, pause, delete, rotate the secret, send a test event, redeliver, list deliveries",[29,30],"[Risk weights](\u002Freference\u002Fmanagement\u002Frisk-weights)","Read, save and restore the organization's and each SDK key's weights, list signals",{"type":32,"level":33,"text":34,"id":35},"heading",2,"Base URL","base-url",{"type":11,"text":37},"The management API is part of your region's API, under `\u002Fapi\u002Fv1\u002Fmanagement`.",{"type":39,"samples":40},"code",[41],{"label":34,"lang":42,"code":43},"text","https:\u002F\u002Fus.api.fingerly.io\u002Fapi\u002Fv1\u002Fmanagement",{"type":11,"text":45},"A management key is refused by any other region's API.",{"type":32,"level":33,"text":47,"id":48},"Management keys","management-keys",{"type":11,"text":50},"Every request is authenticated with a **management key** in the `x-api-key` header. Management keys look like `fly_mk_us_…`: they belong to your organization and region, and to no environment, because they manage keys in all three.",{"type":52,"items":53},"list",[54,55,56,57],"Owners and admins issue them in **Integration > Management keys**. The key is shown once.","A management key cannot issue or revoke management keys, so a leaked one cannot replace itself.","Management keys are for servers. A request carrying a browser `Origin` header is refused, however valid the key.","Only a keyed hash of each key is stored, as for every other key. See [security](\u002Fdocs\u002Fsecurity).",{"type":59,"tone":60,"text":61},"callout","warning","A management key can issue secret keys, which read your visitors' events. Keep it in a secret manager, give it the least powerful role that works, and revoke it the moment it leaks.",{"type":32,"level":33,"text":63,"id":64},"Roles","roles",{"type":11,"text":66},"Each management key acts with a role, chosen when it is issued, and may do exactly what a member with that role may do.",{"type":14,"columns":68,"rows":72},[69,70,71],"Capability","Admin key","Developer key",[73,76,78,80,83],[74,75,75],"List, issue and revoke SDK keys, and change allowed origins","Yes",[77,75,75],"Manage webhook endpoints",[79,75,75],"Read risk weights and the signal list",[81,75,82],"Change risk weights and thresholds","No",[84,75,82],"List, issue and revoke proxy keys",{"type":11,"text":86},"A request the role does not allow answers `403` with the code `insufficient_role`.",{"type":32,"level":33,"text":88,"id":89},"Describe the key","describe-the-key",{"type":91,"method":92,"path":93,"auth":94},"endpoint","GET","\u002Fapi\u002Fv1\u002Fmanagement\u002Fkey","management",{"type":11,"text":96},"Every other route names your organization in its path. Read its ID here, so a tool configured with nothing but a key can find it.",{"type":98,"title":99,"fields":100},"fields","Response",[101,105,108,111,114],{"name":102,"type":103,"text":104},"key_id","string","The management key's ID.",{"name":106,"type":103,"text":107},"organization_id","The organization every management route acts on.",{"name":109,"type":103,"text":110},"name","The key's name.",{"name":112,"type":103,"text":113},"role","`admin` or `developer`.",{"name":115,"type":103,"text":116},"region","The key's data region, such as `us`.",{"type":32,"level":33,"text":118,"id":119},"Conventions","conventions",{"type":52,"items":121},[122,123,124,125,126],"Request and response bodies are JSON, and errors use the [usual error body](\u002Freference\u002Ferrors).","Secrets, of SDK keys, proxy keys and webhook endpoints, are returned once, in the response that creates them. Every later read shows only their last four characters.","Revoking is permanent and nothing is deleted, except webhook endpoints, which are removed.","Changes take effect on the next request: a revoked key is refused and saved weights score the next identification.","Changes made with a management key are attributed to no member: `created_by` and `revoked_by` are omitted.",{"type":32,"level":33,"text":128,"id":129},"Errors","errors",{"type":14,"columns":131,"rows":135},[132,133,134],"Status","Code","When",[136,140,144,148,152],[137,138,139],"`401`","`unauthorized`","The key is missing, unknown, revoked, expired, from another region, or sent from a browser.",[141,142,143],"`403`","`insufficient_role`","The key's role does not allow the operation.",[145,146,147],"`404`","`not_found`","No such resource in the key's organization, including a path naming another organization.",[149,150,151],"`409`","Varies","The resource is in a state that forbids the change, such as an SDK key that is already revoked.",[153,150,154],"`422`","The body is not valid. `error.message` says what to fix.",{"type":59,"tone":156,"text":157},"tip","The whole API is described in the [OpenAPI document](\u002Freference\u002Fopenapi), which client generators and Postman can import.",{"type":159,"columns":33,"cards":160},"cards",[161,166],{"title":162,"text":163,"href":164,"icon":165},"SDK keys","Issue and revoke keys from code.","\u002Freference\u002Fmanagement\u002Fsdk-keys","key",{"title":167,"text":168,"href":169,"icon":170},"Risk weights","Keep your scoring policy in version control.","\u002Freference\u002Fmanagement\u002Frisk-weights","sliders",{"request":172,"response":181},[173,177],{"label":174,"lang":175,"code":176},"cURL","bash","curl \"https:\u002F\u002Fus.api.fingerly.io\u002Fapi\u002Fv1\u002Fmanagement\u002Fkey\" \\\n  -H \"x-api-key: $FINGERLY_MANAGEMENT_KEY\"",{"label":178,"lang":179,"code":180},"Node.js","ts","const response = await fetch('https:\u002F\u002Fus.api.fingerly.io\u002Fapi\u002Fv1\u002Fmanagement\u002Fkey', {\n  headers: { 'x-api-key': process.env.FINGERLY_MANAGEMENT_KEY! },\n})\nconst { organization_id } = await response.json()",[182,186],{"label":183,"lang":184,"code":185},"200","json","{\n  \"key_id\": \"01a0a862-5e3f-7b01-c2d4-6f7a8b9c0d1e\",\n  \"organization_id\": \"01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37\",\n  \"name\": \"Terraform\",\n  \"role\": \"admin\",\n  \"region\": \"us\"\n}",{"label":187,"lang":184,"code":188},"401","{\n  \"error\": {\n    \"code\": \"unauthorized\",\n    \"message\": \"the x-api-key header is not a valid management key\",\n    \"status\": 401\n  },\n  \"request_id\": \"01a0a84c-0f11-7a3e-9c2d-4b5e6f708192\"\n}",[190,191,192,193,194,195],{"id":35,"text":34,"level":33},{"id":48,"text":47,"level":33},{"id":64,"text":63,"level":33},{"id":89,"text":88,"level":33},{"id":119,"text":118,"level":33},{"id":129,"text":128,"level":33},"2026-09-17T16:56:08.000Z",1789667797859]