Commit 9057794c authored by ale's avatar ale

Start adding API reference documentation

parent f7837166
......@@ -130,3 +130,157 @@ Actions:
### web hosting (website / db / FTP account or equivalent)
...
# API Reference
## User endpoints
The following API endpoints invoke operations on an individual
user. Access is allowed for admins, and for the user itself.
Most requests dealing with encryption keys are so-called *privileged*
requests, and will require the user's password in the *cur_password*
parameter in order to decrypt the existing encryption keys.
### `/api/user/get`
Retrieve information about a user and all its associated resources.
Request parameters:
* `username` - user to fetch
* `sso` - SSO ticket
### `/api/user/change_password`
Change the primary authentication password for a user. This operation
will update the user's storage encryption keys, or initialize them if
they do not exist.
Request parameters:
* `username` - name of the user
* `sso` - SSO ticket
* `cur_password` - current valid password for the user
* `password` - new password (unencrypted)
### `/api/user/set_password_recovery_hint`
Sets the secondary authentication password (a hint / response pair,
used to recover the primary credentials) for a user. This operation
will update the user's storage encryption keys, or initialize them if
they do not exist yet.
Request parameters:
* `username` - name of the user
* `sso` - SSO ticket
* `cur_password` - current valid password for the user
* `hint` - the secondary authentication hint
* `response` - the secondary authentication response (effectively a
password, unencrypted)
### `/api/user/enable_otp`
Enable TOTP for a user. The server can generate a new TOTP secret if
necessary, or it can be generated by the caller (usually better as it
allows for a better validation UX).
Request parameters:
* `username` - name of the user
* `sso` - SSO ticket
* `totp_secret` - new TOTP secret (optional)
### `/api/user/disable_otp`
Disable TOTP for a user. Existing 2FA credentials will be wiped as
well.
Request parameters:
* `username` - name of the user
* `sso` - SSO ticket
### `/api/user/create_app_specific_password`
Create a new application-specific password. 2FA must already be
enabled for the user. A new random password will be generated by the
server and returned in the response. A new copy of the encryption key
will be encrypted with the new application-specific password.
ASPs are identified by a unique random ID that is also automatically
generated by the server.
Request parameters:
* `username` - name of the user
* `sso` - SSO ticket
* `cur_password` - current valid password for the user
* `service` - service that the password should be valid for
* `notes` - a user-controlled comment about the client
### `/api/user/delete_app_specific_password`
Delete an application-specific password (and the associated encryption
key).
Request parameters:
* `username` - name of the user
* `sso` - SSO ticket
* `asp_id` - ID of the app-specific password
## Resource endpoints
These API endpoints manipulate individual resources regardless of
which user they belong to. Access is normally granted to admins and to
the user that owns a resource, but some operations are restricted to
admins only.
### `/api/resource/enable`
Enable a resource (admin-only).
Request parameters:
* `resource_id` - resource ID
* `sso` - SSO ticket
* `comment` - notes on the operation
### `/api/resource/disable`
Disable a resource (admin-only).
Request parameters:
* `resource_id` - resource ID
* `sso` - SSO ticket
* `comment` - notes on the operation
### `/api/resource/move`
Move a resource between shards (admin-only).
Resources that are part of a group (for instance websites and DAV
accounts) are moved together, so this request might end up moving more
than one resource.
Request parameters:
* `resource_id` - resource ID
* `sso` - SSO ticket
* `shard` - new shard
### `/api/resource/create`
Create one or more resources associated with a user. Note that if
creating multiple resources, they must all belong to the same user.
Request parameters:
* `sso` - SSO ticket
* `resources` - list of resource objects to create
......@@ -321,7 +321,7 @@ func (s *AccountService) disable2FA(ctx context.Context, tx TX, user *User) erro
type CreateApplicationSpecificPasswordRequest struct {
PrivilegedRequestBase
Service string `json:"service"`
Comment string `json:"comment"`
Notes string `json:"notes"`
}
// Validate the request.
......@@ -354,7 +354,7 @@ func (s *AccountService) CreateApplicationSpecificPassword(ctx context.Context,
asp := &AppSpecificPasswordInfo{
ID: randomAppSpecificPasswordID(),
Service: req.Service,
Comment: req.Comment,
Comment: req.Notes,
}
password := randomAppSpecificPassword()
encPass := pwhash.Encrypt(password)
......
......@@ -146,8 +146,8 @@ func (s *AccountServer) Handler() http.Handler {
h.HandleFunc("/api/user/set_password_recovery_hint", s.withTx(s.handleSetPasswordRecoveryHint))
h.HandleFunc("/api/user/enable_otp", s.withTx(s.handleEnableOTP))
h.HandleFunc("/api/user/disable_otp", s.withTx(s.handleDisableOTP))
h.HandleFunc("/api/app_specific_password/create", s.withTx(s.handleCreateApplicationSpecificPassword))
h.HandleFunc("/api/app_specific_password/delete", s.withTx(s.handleDeleteApplicationSpecificPassword))
h.HandleFunc("/api/user/create_app_specific_password", s.withTx(s.handleCreateApplicationSpecificPassword))
h.HandleFunc("/api/user/delete_app_specific_password", s.withTx(s.handleDeleteApplicationSpecificPassword))
h.HandleFunc("/api/resource/enable", s.withTx(s.handleEnableResource))
h.HandleFunc("/api/resource/disable", s.withTx(s.handleDisableResource))
h.HandleFunc("/api/resource/create", s.withTx(s.handleCreateResources))
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment