Management API: Manage Keys, Webhooks and Weights

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.

Resource	Operations
SDK keys	List, issue, revoke, replace allowed origins
Proxy keys	List, issue, revoke
Webhook endpoints	List, create, update, pause, delete, rotate the secret, send a test event, redeliver, list deliveries
Risk weights	Read, save and restore the organization's and each SDK key's weights, list signals

Base URL

The management API is part of your region's API, under /api/v1/management.

Base URL

https://us.api.fingerly.io/api/v1/management

A management key is refused by any other region's API.

Management keys

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.

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.

Roles

Each management key acts with a role, chosen when it is issued, and may do exactly what a member with that role may do.

Capability	Admin key	Developer key
List, issue and revoke SDK keys, and change allowed origins	Yes	Yes
Manage webhook endpoints	Yes	Yes
Read risk weights and the signal list	Yes	Yes
Change risk weights and thresholds	Yes	No
List, issue and revoke proxy keys	Yes	No

A request the role does not allow answers 403 with the code insufficient_role.

Describe the key

GET/api/v1/management/key Management key

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.

Response

key_idstring
The management key's ID.
organization_idstring
The organization every management route acts on.
namestring
The key's name.
rolestring
admin or developer.
regionstring
The key's data region, such as us.

Conventions

Request and response bodies are JSON, and errors use the usual error body.
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.

Errors

Status	Code	When
`401`	`unauthorized`	The key is missing, unknown, revoked, expired, from another region, or sent from a browser.
`403`	`insufficient_role`	The key's role does not allow the operation.
`404`	`not_found`	No such resource in the key's organization, including a path naming another organization.
`409`	Varies	The resource is in a state that forbids the change, such as an SDK key that is already revoked.
`422`	Varies	The body is not valid. `error.message` says what to fix.

SDK keysIssue and revoke keys from code.Risk weightsKeep your scoring policy in version control.