Use the Fing Cloud API with your own scripts and tools

The Fing Cloud API lets your own scripts, dashboards and automations read what Fing knows about your networks: workspaces, networks, devices, contacts, events, speed test results and router vulnerability scans. You authenticate with a client id and secret you create in your account, exchange them for a short-lived token and call the API over HTTPS. This article explains how to create and manage those credentials, how to make your first call and how to keep the credentials safe.

What the Cloud API is for

Use it when you want Fing data somewhere Fing does not go by itself:

• a home or office dashboard that shows which devices are online and when the last speed test ran;
• a script that exports the device inventory of every network you manage;
• an alerting tool that reads the event log and warns you about new devices or outages;
• any integration platform that can call a REST API with a bearer token.

The full list of endpoints, parameters and response schemas is in the Cloud API reference. The OpenAPI specification at https://app.fing.com/cloud/docs/api-spec lets you generate a client in your language of choice.

Where to manage your credentials

Sign in at app.fing.com, open Access from the account navigation and select the Cloud API tab. My credentials lists the clients you created:

• Name: the label you gave the client, with an Inactive badge when you paused it.
• Secret: the last four characters of the secret, so you can tell which secret a script holds. The full secret is never shown again after creation.
• Scopes: what a token issued to this client may do.
• Created and Last used: when you created the client and the last time its secret was used to request a token.

Accounts without a Professional plan can see this list but cannot create or change clients.

Create a client

1. On the Cloud API tab, click Create client.
2. Enter a name that tells you what the client is for, such as 'Home dashboard', and click Create.
3. Fing shows the client id and the client secret. Copy both with the Copy buttons and store them somewhere safe, such as a password manager or your tool's secret store.
4. Click I have saved the secret. The dialog has no other way to close, because the secret cannot be shown again.

A new client starts with the api_read, api_write and api_provisioning scopes and is active. Only api_read has endpoints behind it during the beta; the other two are reserved for the write and provisioning operations that will follow.

Make your first call

1. Request an access token

The Cloud API uses the OAuth 2.0 client credentials grant. Exchange the client id and secret for a token:

curl -X POST https://app.fing.com/rest/auth/external/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

The response holds the token, its lifetime in seconds and the scopes it carries:

{
  "token_type": "Bearer",
  "access_token": "…",
  "expires_in": 3600,
  "scope": "api_read api_write api_provisioning"
}

A token is valid for one hour and comes without a refresh token: when it expires, request a new one with the same call. Request a token when your script starts rather than once per API call.

2. Call the API

Send the token in the Authorization header of every request:

curl https://app.fing.com/cloud/v1/networks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This lists your networks. Each one carries a networkRef that the other endpoints take as input, for example /cloud/v1/network/{networkRef}/devices for its devices. See the Cloud API reference for every endpoint.

Errors and limits

Every response reports the limits that apply to your client. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset describe the short-term allowance; X-RateLimit-Limit-Monthly, X-RateLimit-Remaining-Monthly and X-RateLimit-Reset-Monthly describe the monthly quota. A limit that is not enforced for your client is left out.

Manage your clients

Each row under My credentials has three buttons: edit, rotate and delete.

Rename, change scopes or pause a client

1. Click the pencil button in the client's row.
2. Change the Name, tick or untick Scopes, or switch Active off to pause the client.
3. Click Save.

At least one scope must stay ticked. Scope changes apply to tokens issued from then on; a token issued earlier keeps its scopes until it expires. A paused client cannot obtain new tokens but keeps its id, secret and settings, which makes it the right choice when you want to stop a script temporarily without re-issuing credentials.

Rotate a secret

Rotate when a secret may have leaked, when a person who knew it leaves, or on a schedule of your own.

1. Click the rotate button, the circular arrows, in the client's row.
2. Read the confirmation and click Rotate secret.
3. Copy the new secret from the dialog and update every script that uses this client, then click I have saved the secret.

The old secret stops working for new token requests at once. Access tokens issued before the rotation keep working until they expire, so a running script has up to an hour to pick up the new secret. The client id does not change.

Delete a client

1. Click the bin button in the client's row.
2. Read the confirmation and click Delete client.

The client is removed permanently and every token issued to it is revoked at once, so anything still using these credentials stops working immediately. If you only want a pause, switch the client off instead.

What happens when your plan changes

Creating and managing clients needs a Fing Professional plan. If your account moves to another plan, your clients stay listed under My credentials but the create, edit, rotate and delete buttons are disabled until you are back on Professional, where you can delete clients you no longer want.

Security checklist

• Store secrets in a password manager, an environment variable or your platform's secret store, never in source code.
• Create one client per script or tool, named after what it does, so a leak affects one thing and Last used tells you which clients are still alive.
• Delete clients you no longer use, and pause the ones you will need again.
• Rotate a secret as soon as you suspect it leaked. If you cannot update the script in time, pause or delete the client.

Troubleshooting

Need help?

Click the Submit a request button at the top right of the page and include the status code and the endpoint you called. Never include the client secret or a token.