auth
The account of the server (its administrator), signing in and out of the dashboard, the sessions and the API tokens, and ferry login (a terminal asks, the dashboard approves). The status, the first-run setup, signing in and out, and the two calls of a terminal need no authentication; the others only accept the dashboard's session, never an API token.
/api/v1/auth/cliWhat ferry login calls first. The terminal then shows code and opens /cli-login?id=<id> of the dashboard, where the signed-in administrator checks the code and approves; meanwhile the terminal polls POST /api/v1/auth/cli/{id}/token with secret. A request waits 10 minutes, and a restart of the server forgets it. No token needed.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /api/v1/auth/cli — a terminal asks to be connected (ferry login).
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/auth/cli" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'{ "code": "string", "expires_in": 0, "id": "string", "interval": 0, "secret": "string"}/api/v1/auth/cli/{id}What the approval page shows: who asks and the code the terminal displays. Needs the dashboard's session.
Authorization
session The dashboard's session: the cookie POST /api/v1/auth/login sets, named ferry_session followed by the port of the address the browser uses (ferry_session_7878). A request that changes something must also come from the dashboard's own origin.
In: cookie
Path Parameters
Id of the request.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/auth/cli/string" \ -H "Authorization: Bearer $FERRY_TOKEN"{ "code": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "status": "pending"}/api/v1/auth/cli/{id}/approveCreates an API token named after the request and hands it to the terminal that asked, the next time it polls. Approve only when the code on the page is the one your terminal shows. Needs the dashboard's session.
Authorization
session The dashboard's session: the cookie POST /api/v1/auth/login sets, named ferry_session followed by the port of the address the browser uses (ferry_session_7878). A request that changes something must also come from the dashboard's own origin.
In: cookie
Path Parameters
Id of the request.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/auth/cli/string/approve" \ -H "Authorization: Bearer $FERRY_TOKEN"{ "code": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "status": "pending"}/api/v1/auth/cli/{id}/denyThe terminal that asked is told so the next time it polls. Needs the dashboard's session.
Authorization
session The dashboard's session: the cookie POST /api/v1/auth/login sets, named ferry_session followed by the port of the address the browser uses (ferry_session_7878). A request that changes something must also come from the dashboard's own origin.
In: cookie
Path Parameters
Id of the request.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/auth/cli/string/deny" \ -H "Authorization: Bearer $FERRY_TOKEN"{ "code": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "status": "pending"}/api/v1/auth/cli/{id}/tokenWhat the terminal polls, every interval seconds, with the secret it got when it started the request. pending until the request is answered; approved comes with the API token, once: the request is gone afterwards, like after denied. No token needed.
Path Parameters
Id of the request.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /api/v1/auth/cli/{id}/token
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/auth/cli/string/token" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "secret": "string" }'{ "status": "pending", "token": "string"}/api/v1/auth/loginChecks the email and password of the account and starts a session: the answer sets the session cookie (HttpOnly, SameSite=Strict; named ferry_session_<port> after the port of the address the browser uses, so that servers sharing a host name keep a session each), which authenticates the dashboard's requests from then on. A session ends 30 days after it was last used. After 10 failed attempts in 5 minutes, sign-ins are refused until the oldest is 5 minutes old. No token needed.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /api/v1/auth/login
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/auth/login" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "string", "password": "string" }'{ "auth": "session", "setup_required": true, "user": { "created_at": "2019-08-24T14:15:22Z", "email": "string", "id": "string" }}/api/v1/auth/logoutEnds the session of the request's cookie and clears the cookie. Succeeds without a session too.
Response Body
application/json
curl -X POST "https://example.com/api/v1/auth/logout" \ -H "Authorization: Bearer $FERRY_TOKEN"/api/v1/auth/passwordNeeds the dashboard's session and the current password. Every other session of the account ends; this one stays. (A forgotten password is replaced on the server with ferryd reset-password.)
Authorization
session The dashboard's session: the cookie POST /api/v1/auth/login sets, named ferry_session followed by the port of the address the browser uses (ferry_session_7878). A request that changes something must also come from the dashboard's own origin.
In: cookie
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /api/v1/auth/password
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/auth/password" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "current_password": "string", "new_password": "string" }'/api/v1/auth/sessionsThe browsers signed in to the account, the last used first; current marks the one of this request. Needs the dashboard's session.
Authorization
session The dashboard's session: the cookie POST /api/v1/auth/login sets, named ferry_session followed by the port of the address the browser uses (ferry_session_7878). A request that changes something must also come from the dashboard's own origin.
In: cookie
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/auth/sessions" \ -H "Authorization: Bearer $FERRY_TOKEN"[ { "created_at": "2019-08-24T14:15:22Z", "current": true, "expires_at": "2019-08-24T14:15:22Z", "id": "string", "last_used_at": "2019-08-24T14:15:22Z", "user_agent": "string" }]/api/v1/auth/sessions/{id}Signs that browser out. Ending the session of this request is signing out. Needs the dashboard's session.
Authorization
session The dashboard's session: the cookie POST /api/v1/auth/login sets, named ferry_session followed by the port of the address the browser uses (ferry_session_7878). A request that changes something must also come from the dashboard's own origin.
In: cookie
Path Parameters
Session id.
Response Body
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/auth/sessions/string" \ -H "Authorization: Bearer $FERRY_TOKEN"/api/v1/auth/setupOnly while the server has no account (setup_required). code is the setup code: ferryd prints it in a link (/setup?code=…) when it starts without an account, and keeps it in <data-dir>/setup_code, so only someone on the server can create the account. The answer signs the browser in (it sets the session cookie). No token needed.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /api/v1/auth/setup — create the administrator's account of a
server that has none.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/auth/setup" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "code": "string", "email": "string", "password": "string" }'{ "auth": "session", "setup_required": true, "user": { "created_at": "2019-08-24T14:15:22Z", "email": "string", "id": "string" }}/api/v1/auth/statusWhat the dashboard asks first. setup_required is true while the server has no account: it is then created with POST /api/v1/auth/setup. auth says how the request is authenticated (session for the dashboard's cookie, token for an API token), or is null when it isn't; credentials that are wrong or expired count as none. No token needed.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/auth/status" \ -H "Authorization: Bearer $FERRY_TOKEN"{ "auth": "session", "setup_required": true, "user": { "created_at": "2019-08-24T14:15:22Z", "email": "string", "id": "string" }}/api/v1/auth/tokensThe named API tokens, the newest first: their name, the end of the token and when they were last used. Never the tokens themselves. The server token of <data-dir>/api_token isn't listed. Needs the dashboard's session.
Authorization
session The dashboard's session: the cookie POST /api/v1/auth/login sets, named ferry_session followed by the port of the address the browser uses (ferry_session_7878). A request that changes something must also come from the dashboard's own origin.
In: cookie
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/auth/tokens" \ -H "Authorization: Bearer $FERRY_TOKEN"[ { "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "hint": "string", "id": "string", "last_used_at": "2019-08-24T14:15:22Z", "name": "string" }]/api/v1/auth/tokensA token for the CLI, a script or CI: it authenticates as Authorization: Bearer <token> and can do everything the API offers except manage the account and its tokens. The answer is the only time the token is shown; the server keeps its SHA-256. Needs the dashboard's session.
Authorization
session The dashboard's session: the cookie POST /api/v1/auth/login sets, named ferry_session followed by the port of the address the browser uses (ferry_session_7878). A request that changes something must also come from the dashboard's own origin.
In: cookie
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /api/v1/auth/tokens
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/auth/tokens" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "api_token": { "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "hint": "string", "id": "string", "last_used_at": "2019-08-24T14:15:22Z", "name": "string" }, "token": "string"}/api/v1/auth/tokens/{id}The token stops working at once. Needs the dashboard's session.
Authorization
session The dashboard's session: the cookie POST /api/v1/auth/login sets, named ferry_session followed by the port of the address the browser uses (ferry_session_7878). A request that changes something must also come from the dashboard's own origin.
In: cookie
Path Parameters
API token id (tok-…).
Response Body
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/auth/tokens/string" \ -H "Authorization: Bearer $FERRY_TOKEN"