Accounts.

A key can read a little about its own account. Creating users and groups, and changing them, needs an administrator key.

See the API reference for the key and for errors. Changing a password or an authenticator app is not in this list.

The signed-in account

GET /api/v1/auth/me

Who the caller is.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "email": "[email protected]",
  "display_name": "example",
  "is_admin": true,
  "csrf_token": "example",
  "totp_enrolled": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/auth/sign-out-everywhere

End every session this account has.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Request body. None.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

GET /api/v1/profile/recovery-codes

How many recovery codes are left.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Success. 200.

{
  "total": 1,
  "unused": 1
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

GET /api/v1/profile/sessions

Where this account is signed in.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Success. 200.

The body is an array.

[
  {
    "id": "k7Qm2sLp9vX4aB1c",
    "createdAt": "2026-10-05T18:00:00Z",
    "lastUsedAt": "2026-10-05T18:00:00Z",
    "expiresAt": "2026-10-05T18:00:00Z",
    "userAgent": "example",
    "ip": "example",
    "current": true
  }
]

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

DELETE /api/v1/profile/sessions/{id}

End one of them.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Parameters.

Success. 200.

{
  "ok": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

Users

GET /api/v1/users

Every account.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Each account has clients: the last version of the farwing command line and of Farwing Desktop it was used from, newest first. Empty for an account only used in a browser.

Success. 200.

The body is an array.

[
  {
    "id": "k7Qm2sLp9vX4aB1c",
    "email": "[email protected]",
    "displayName": "example",
    "isAdmin": true,
    "disabled": true,
    "totpEnrolled": true,
    "totpRequired": true,
    "hasPassword": true,
    "createdAt": "2026-10-05T18:00:00Z"
  }
]

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/users

Make an account.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "email": "[email protected]",
  "displayName": "example",
  "password": "a-secret-shown-once",
  "isAdmin": true,
  "totpRequired": true
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "email": "[email protected]",
  "displayName": "example",
  "isAdmin": true,
  "disabled": true,
  "totpEnrolled": true,
  "totpRequired": true,
  "hasPassword": true,
  "createdAt": "2026-10-05T18:00:00Z"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "the address is taken, or the password was refused"
  }
}

PATCH /api/v1/users/{id}

Change an account. The last administrator cannot be demoted or disabled.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "displayName": "example",
  "isAdmin": true,
  "disabled": true,
  "totpRequired": true
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "email": "[email protected]",
  "displayName": "example",
  "isAdmin": true,
  "disabled": true,
  "totpEnrolled": true,
  "totpRequired": true,
  "hasPassword": true,
  "createdAt": "2026-10-05T18:00:00Z"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "the change would leave the server with no administrator"
  }
}

DELETE /api/v1/users/{id}

Delete an account.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Success. 200.

{
  "deleted": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "you cannot delete your own account"
  }
}

POST /api/v1/users/{id}/password

Set someone's password. Signs them out everywhere.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "password": "a-secret-shown-once"
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "email": "[email protected]",
  "displayName": "example",
  "isAdmin": true,
  "disabled": true,
  "totpEnrolled": true,
  "totpRequired": true,
  "hasPassword": true,
  "createdAt": "2026-10-05T18:00:00Z"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "the request is not valid"
  }
}

POST /api/v1/users/{id}/clear-second-factor

Clear a lost authenticator, and its recovery codes.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Request body. None.

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "email": "[email protected]",
  "displayName": "example",
  "isAdmin": true,
  "disabled": true,
  "totpEnrolled": true,
  "totpRequired": true,
  "hasPassword": true,
  "createdAt": "2026-10-05T18:00:00Z"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

Groups

GET /api/v1/admin/groups

Every group, with how many people are in it and how many folders it reaches.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

The body is an array.

[
  {
    "id": "k7Qm2sLp9vX4aB1c",
    "name": "Rush delivery",
    "createdAt": "2026-10-05T18:00:00Z",
    "members": 1,
    "shares": 1
  }
]

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/admin/groups

Make a group.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "name": "Rush delivery"
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "createdAt": "2026-10-05T18:00:00Z",
  "members": 1,
  "shares": 1
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "conflict",
    "message": "the name is taken"
  }
}

GET /api/v1/admin/groups/{id}

One group, its members and its shared folders.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "createdAt": "2026-10-05T18:00:00Z",
  "members": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "email": "[email protected]",
      "displayName": "example"
    }
  ],
  "shares": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "rootId": "k7Qm2sLp9vX4aB1c",
      "rootName": "example",
      "path": "projects/rush",
      "canRead": true,
      "canWrite": true,
      "canDelete": true
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

PATCH /api/v1/admin/groups/{id}

Rename it.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "name": "Rush delivery"
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "createdAt": "2026-10-05T18:00:00Z",
  "members": 1,
  "shares": 1
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "conflict",
    "message": "the name is taken"
  }
}

DELETE /api/v1/admin/groups/{id}

Remove it. Memberships and grants go; no file is touched.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/admin/groups/{id}/members

Put somebody in the group. Doing it twice is not an error.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "userId": "k7Qm2sLp9vX4aB1c"
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "createdAt": "2026-10-05T18:00:00Z",
  "members": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "email": "[email protected]",
      "displayName": "example"
    }
  ],
  "shares": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "rootId": "k7Qm2sLp9vX4aB1c",
      "rootName": "example",
      "path": "projects/rush",
      "canRead": true,
      "canWrite": true,
      "canDelete": true
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "no such account"
  }
}

DELETE /api/v1/admin/groups/{id}/members/{user_id}

Take them out again.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/admin/groups/{id}/shares

Give the group a folder, or change the rights it has on one. Prefer a space grant.

Still served, so an older script keeps working. New scripts should use spaces.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "rootId": "k7Qm2sLp9vX4aB1c",
  "path": "projects/rush",
  "canRead": true,
  "canWrite": true,
  "canDelete": true
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "rootName": "example",
  "path": "projects/rush",
  "canRead": true,
  "canWrite": true,
  "canDelete": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "a share with none of read, write or delete"
  }
}

DELETE /api/v1/admin/groups/{id}/shares/{grant_id}

Take the folder away. Nothing is deleted.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

The signed-in account

GET /api/v1/profile/traffic

The caller's own effective speed limits.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Success. 200.

{
  "perTransferBps": 1,
  "poolBps": 1,
  "concurrency": 1,
  "limitedBy": "example",
  "sentence": "example",
  "layers": [
    {
      "kind": "file",
      "id": "k7Qm2sLp9vX4aB1c",
      "groupKind": "example",
      "totalBps": 1,
      "perTransferBps": 1,
      "concurrency": 1,
      "overridden": [
        "example"
      ]
    }
  ],
  "winners": {
    "total": "example",
    "perTransfer": "example",
    "concurrency": "example"
  }
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

Farwing docs · farwing.io