ReferenceAPI overview
API tokens
An API token is fy_ and 40 hex characters. There are three kinds, all with the same access.
An API token is fy_, then 40 hex characters.
The three kinds
| Kind | Where it comes from | In the dashboard |
|---|---|---|
| Named token | You create it in the dashboard: Server → Account. It can have an expiry. | In the list. You can revoke it. |
| Token of a terminal | ferry login gets it after you approve the request in the dashboard. | In the same list. You revoke it the same way. |
| server token | The file <data-dir>/api_token (mode 0600). ferryd makes it at the first start, or you set it with --api-token / FERRY_API_TOKEN. | Not in the list. You cannot revoke it there. |
The server token is for scripts on the server itself.
What a token can do
A token can do all in the API, but it cannot use the account endpoints. Ferry has one administrator account and no roles. See The administrator account.
The dashboard shows a named token one time, when you create it. The server keeps only its SHA-256 digest.
- A
GETrequest can give the token as?access_token=<token>. The reason: the EventSource of a browser cannot set headers. - Other methods accept only the header.
- Use the header when you can. A URL goes into the history of the browser and into the logs of each proxy before the server.