This page describes how an app logs a user in to their Nova account without ever seeing their password. It is complete: a developer, or a coding assistant, can build the login from this page alone, without reading Nova’s source code.
Summary#
- The protocol is the OAuth 2.0 authorization code flow (RFC 6749) with PKCE (RFC 7636), used the way RFC 8252 prescribes for apps which run on the user’s own device.
- There is no client secret, no refresh token and no expiry time in the response.
- What the app gets in the end is an ordinary Nova API key. It sends the key as a Bearer token with every API request.
- The key has only the permissions the app asked for, and the user can limit it to certain directories.
Everything on this page runs on the test cluster https://dev.nova.storage.
Accounts on it are separate from the ones on nova.storage. Make the base URL a
setting in your app: the production site will use the same paths on another
host.
| What | Method | URL |
|---|---|---|
| Authorization page (browser) | GET | https://dev.nova.storage/oauth/authorize |
| Token endpoint (app) | POST | https://dev.nova.storage/api/user/oauth/token |
| Everything else in the API | https://dev.nova.storage/api/... |
Registered apps#
An app has to be registered by Nova before it can use this. A request from an app which is not in this list, or with a redirect URI which does not match its registration, ends on an error page.
client_id |
Name the user sees | Redirect URI |
|---|---|---|
jevido-nova |
Jevido Nova App | http://127.0.0.1:{port}/oauth/callback |
The redirect URI is compared to the letter, except for the port:
- The scheme is
httpand the host is127.0.0.1. Notlocalhost, not[::1], nothttps. {port}is any port number from 0 to 65535. The app picks a free one each time it logs in.- The path is exactly
/oauth/callback. No trailing slash, no query string.
The flow#
1. Make the secrets#
Before every login the app makes two random values:
code_verifier: 43 to 128 characters fromA-Z,a-z,0-9,-,.,_and~. The simple way is 32 random bytes from a cryptographic random source, encoded as base64url without padding, which gives 43 characters.state: any random string of up to 2000 characters. Make it the same way.
From the verifier it computes the challenge:
code_challenge = base64url_without_padding(sha256(ascii(code_verifier)))The result is always 43 characters. To test your code: the verifier
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk has the challenge
E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM.
The app keeps the verifier and the state in memory until the login is done. It never puts the verifier in a URL.
2. Listen for the answer#
The app starts an HTTP server on 127.0.0.1, on any free port. Its redirect URI
for this login is http://127.0.0.1:{port}/oauth/callback, with that port in
it.
3. Send the user to the authorization page#
The app opens this URL in the default browser of the user. It must be the real browser, not a web view inside the app: the user is usually logged in to Nova there already, and they have to be able to see that the page is Nova’s.
https://dev.nova.storage/oauth/authorize
?response_type=code
&client_id=jevido-nova
&redirect_uri=http%3A%2F%2F127.0.0.1%3A41234%2Foauth%2Fcallback
&scope=filesystem_read+filesystem_write+account_read
&state=Yf3mE0k...
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256(The line breaks are only there for reading.) All values are URL encoded.
| Parameter | Required | Value |
|---|---|---|
response_type |
yes | code |
client_id |
yes | The ID the app is registered with |
redirect_uri |
yes | See Registered apps, at most 2000 characters |
scope |
yes | One or more names from Scopes, with spaces in between |
state |
no | Comes back unchanged with the answer. The app should always send it |
code_challenge |
yes | Exactly 43 characters, see step 1 |
code_challenge_method |
yes | S256. The plain method is not supported |
Rules:
- Send every parameter once. A request which has a parameter in it twice is not reliable.
- Do not send
filesystem_dirs. The request is refused if it has that parameter. Which directories the app can use is for the user to choose. - Other parameters are ignored.
What the user sees:
- If they are not logged in to Nova in this browser, the login page. After logging in they continue to the next step by themselves.
- A page which says that the app (by the name it is registered with) wants access to their account, on which account they are logged in, and what the app will be able to do. If the app asked for a filesystem scope they can pick directories to limit the app to.
- The buttons Approve and Deny.
4. Receive the answer#
When the user chooses, the browser makes a GET request to the redirect URI.
If they approved:
GET /oauth/callback?code=75e48c59-0b1d-4e9a-9d0c-3c1f6d2b8a11&state=Yf3mE0k...If they denied:
GET /oauth/callback?error=access_denied&state=Yf3mE0k...The app must check that state is the value it sent, and ignore the request if
it is not. It answers the browser with a short page which says that the user
can close the tab and go back to the app, and then stops listening.
The app does not always get an answer. When the request is not valid the user stays on an error page of Nova and the browser is not sent back, see Errors on the authorization page. The user can also just close the tab. So the app needs a way to cancel a login which is waiting, and should give up by itself after some minutes.
5. Trade the code for the key#
The code is valid for five minutes and can be used once. The app sends it to the token endpoint right away:
POST https://dev.nova.storage/api/user/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=75e48c59-0b1d-4e9a-9d0c-3c1f6d2b8a11
&redirect_uri=http%3A%2F%2F127.0.0.1%3A41234%2Foauth%2Fcallback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk| Parameter | Required | Value |
|---|---|---|
grant_type |
yes | authorization_code |
code |
yes | The code from step 4 |
redirect_uri |
yes | The same string as in step 3, with the same port |
code_verifier |
yes | The verifier from step 1 |
Do not send an Authorization header with this request. (A library which
sends the client ID as the user name of a Basic header with an empty password
does work. A password in that header is taken for an API key.) client_id is
allowed in the form but not needed.
The answer to a good request has status 200 and this JSON body:
{
"access_token": "c7d8ca5d-3b0e-4b0a-9a5e-0f6f0c7a1b22",
"token_type": "Bearer",
"scope": "filesystem_read filesystem_write account_read",
"filesystem_dirs": []
}access_tokenis the API key. Keep it secret and store it where the operating system keeps credentials, if there is such a place.scopeis what the app asked for.filesystem_dirsis the list of directories the user limited the app to. An empty list means there is no limit. Store this list together with the key, see Directory limits. A key without thesession_readscope has no way to ask for it later.- There is no
expires_inand norefresh_token.
A request which is refused has status 400 and a body in the format of RFC 6749 section 5.2:
{
"error": "invalid_grant",
"error_description": "The code is not valid, it expired, it was used before, or the redirect_uri or code_verifier does not match the request it was given out for"
}error |
Cause |
|---|---|
invalid_request |
A parameter is missing or malformed, or grant_type is not authorization_code |
invalid_grant |
The code is unknown, expired or used, or redirect_uri or code_verifier do not match |
After either error the login has to start again from step 1. Do not retry the same code.
6. Use the key#
Send the key with every API request in this header, with exactly this spelling, a capital B and one space:
Authorization: Bearer c7d8ca5d-3b0e-4b0a-9a5e-0f6f0c7a1b22HTTP Basic authentication with an empty user name and the key as the password works too.
Scopes#
The scope of a request is a list of these names with spaces in between. Ask for as little as the app needs: the user sees every permission on the page where they approve the app.
| Scope | What the key can do |
|---|---|
filesystem_read |
List directories, read file information, download and search files |
filesystem_write |
Upload, create directories, rename, move, delete, and change how files are shared |
account_read |
GET /api/user (user name, e-mail address, plan, storage and transfer usage) and the usage statistics |
session_read |
List the API keys of the account which can do no more than this key |
session_write |
Create API keys which can do no more than this key |
billing_read |
See invoices and transactions |
billing_write |
Create invoices and change the subscription |
A file manager needs filesystem_read filesystem_write account_read.
There is no scope for changing the account itself. The user name, e-mail address, password and two-factor login can only be changed by the user, logged in on the website. No API key which an app can get is able to do that.
A request can only be approved for permissions which the login session of the user has itself. For a normal login on the website that is all of them.
Directory limits#
On the authorization page the user can pick directories. The key then only
works inside those directories, and the token response lists them in
filesystem_dirs as directory IDs:
"filesystem_dirs": ["6m6r7854Ubzt491q4AJuCb", "kPH3q7JP4Syg6Fi5HSemA"]How the app has to deal with that:
- If the list is empty there is no limit. The home directory of the user is
/api/filesystem/me, as usual. - If the list is not empty, do not use
me. Every ID in the list is a root of its own. The path of something inside it is/api/filesystem/{id}/{path inside the directory}. Show the directories as the top level locations of the app. - The name of such a directory is in
path[0].nameof the response toGET /api/filesystem/{id}?stat. Thepathfields of the nodes in a response start with/{id}, where they would start with/mein the home directory. - Anything outside the listed directories is refused with status 400 and the
error
permission_denied. That goes for files the app may expect in the home directory too, like/me/.nova/bookmarks.json. - A rename can not move something from one listed directory to another: the old and the new path have to be under the same root.
- The user can change the directories of the key afterwards, and its
permissions, on the API keys page of the website. The app is not told. If
requests which used to work are refused with
permission_deniedorkey_permission_denied, the app should ask the user to log in again. That gives it a new key, with the directories as they are then. A key with thesession_readscope can look itself up instead: it is the entry with"current": truein the response ofGET /api/user/session, which has the fieldsfilesystem_dirsand one boolean per scope.
Example with the first directory of the list above:
GET https://dev.nova.storage/api/filesystem/6m6r7854Ubzt491q4AJuCb?stat
Authorization: Bearer c7d8ca5d-3b0e-4b0a-9a5e-0f6f0c7a1b22{
"path": [
{"id": "6m6r7854Ubzt491q4AJuCb", "type": "dir", "path": "/6m6r7854Ubzt491q4AJuCb", "name": "Backups"}
],
"base_index": 0,
"children": [
{"id": "MoDmdQKTq3P1FMPoRcoATw", "type": "file", "path": "/6m6r7854Ubzt491q4AJuCb/example.txt", "name": "example.txt"}
],
"permissions": {"owner": true, "read": true, "write": true, "delete": true}
}(The nodes have more fields than are shown here.)
How long the key lives#
- The key stays valid as long as it is used. It expires when it has not been used for 30 days.
- The user can delete the key at any moment, on the API keys page of the website.
- In both cases the next request gets status 401 with the error
authentication_failed. There is no refresh token: the app forgets the key and starts the login again. - To sign out, the app deletes its own key with
DELETE https://dev.nova.storage/api/user/session, with the key in theAuthorizationheader. Every key can do this, whatever its scope. Do it whenever the user signs out of the app.
Errors#
Apart from the token endpoint, the API reports errors with an HTTP status and
this JSON body. value is the stable name of the error.
{"success": false, "value": "authentication_failed", "message": "The provided API key is invalid, has been revoked or has expired"}| Status | value |
Meaning |
|---|---|---|
| 401 | authentication_failed |
The key does not exist anymore. Log in again |
| 401 | authentication_required |
The request had no key |
| 403 | key_permission_denied |
The key does not have the scope which this endpoint needs |
| 400 | permission_denied |
The filesystem path is outside what the key or the user is allowed to use |
Errors on the authorization page#
When the request of step 3 is not valid, the user gets a page which says that the app can’t be given access, with the message of the error. The browser is not sent back to the app. These are the errors, by the name they have in the API:
value |
Cause |
|---|---|
oauth_client_invalid |
Unknown client_id, or a redirect_uri which the app did not register |
oauth_scope_invalid |
A name in scope which is not in the table of scopes |
oauth_dirs_invalid |
The request has a filesystem_dirs parameter |
missing_field, enum_parse_failed, string_out_of_range |
A parameter is missing, has a value which is not allowed, or has the wrong length. The page names the parameter |
key_permission_denied |
The login session of the user can not give out the permissions which were asked for |
What is not supported#
- Refresh tokens, client secrets, the implicit flow, the device flow and the
plainPKCE method. - Redirect URIs with a custom scheme, like
myapp://callback. Only the ones in the list of registered apps work. An app which can not listen on127.0.0.1while the browser is open, which happens on phones, needs another redirect URI registered first. - A discovery document. The URLs on this page are all there is.
- Apps which run as a web page on another site: the API does not send the CORS headers a browser needs for that.
Checklist#
- A new
code_verifierandstatefor every login, from a cryptographic random source. code_challengeis the SHA-256 hash of the verifier in base64url without=padding. Check it with the test values in step 1.- The listener is on
127.0.0.1, and the redirect URI says127.0.0.1. - The path of the redirect URI is
/oauth/callback. - The login page opens in the default browser, not in a web view.
- The app checks
statebefore it uses the code. - The token request has the same
redirect_urias the authorization request, and noAuthorizationheader. - The app stores
access_tokenandfilesystem_dirs. - If
filesystem_dirsis not empty the app uses those IDs as roots, and neverme. - A waiting login can be cancelled, and gives up by itself.
- On status 401
authentication_failedthe app asks the user to log in again. - Signing out deletes the key with
DELETE /api/user/session.
Reference implementation#
This is a complete login in Go with only the standard library. It was run against the API as it is described here.
// Package novaauth logs a user in to Nova with OAuth 2.0: the authorization
// code flow with PKCE and a loopback redirect. Standard library only.
package novaauth
import (
"context"
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
"net"
"net/http"
"net/url"
"strings"
)
// Token is the response of the token endpoint. Store all of it.
type Token struct {
AccessToken string `json:"access_token"`
TokenType string `json:"token_type"`
Scope string `json:"scope"`
FilesystemDirs []string `json:"filesystem_dirs"`
}
// random returns 43 characters which are safe in a URL
func random() string {
b := make([]byte, 32)
if _, err := rand.Read(b); err != nil {
panic(err)
}
return base64.RawURLEncoding.EncodeToString(b)
}
// Login runs the whole flow and returns the API key of the user.
//
// base is the site, "https://dev.nova.storage". scope is a list of permissions
// with spaces in between. openBrowser has to open a URL in the default browser
// of the user. Cancel ctx to stop waiting for the user.
func Login(
ctx context.Context,
base, clientID, scope string,
openBrowser func(url string) error,
) (*Token, error) {
verifier, state := random(), random()
sum := sha256.Sum256([]byte(verifier))
challenge := base64.RawURLEncoding.EncodeToString(sum[:])
// Any free port, on 127.0.0.1. "localhost" is not accepted
listener, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
return nil, err
}
port := listener.Addr().(*net.TCPAddr).Port
redirectURI := fmt.Sprintf("http://127.0.0.1:%d/oauth/callback", port)
type result struct {
code string
err error
}
results := make(chan result, 1)
server := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
q := r.URL.Query()
if r.URL.Path != "/oauth/callback" || q.Get("state") != state {
// Not the answer to our request, keep waiting
http.Error(w, "unexpected request", http.StatusBadRequest)
return
}
var res result
if q.Get("error") != "" {
res.err = errors.New("login was not approved: " + q.Get("error"))
} else if res.code = q.Get("code"); res.code == "" {
res.err = errors.New("the callback has no code")
}
fmt.Fprintln(w, "You can close this tab and go back to the app.")
select {
case results <- res:
default: // A second callback, the first one counts
}
})}
go server.Serve(listener)
defer server.Close()
if err = openBrowser(base + "/oauth/authorize?" + url.Values{
"response_type": {"code"},
"client_id": {clientID},
"redirect_uri": {redirectURI},
"scope": {scope},
"state": {state},
"code_challenge": {challenge},
"code_challenge_method": {"S256"},
}.Encode()); err != nil {
return nil, err
}
var res result
select {
case res = <-results:
case <-ctx.Done():
return nil, ctx.Err()
}
if res.err != nil {
return nil, res.err
}
// Trade the code for the key. No Authorization header on this request
req, err := http.NewRequestWithContext(
ctx, "POST", base+"/api/user/oauth/token",
strings.NewReader(url.Values{
"grant_type": {"authorization_code"},
"code": {res.code},
"redirect_uri": {redirectURI},
"code_verifier": {verifier},
}.Encode()),
)
if err != nil {
return nil, err
}
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
var e struct {
Error string `json:"error"`
Description string `json:"error_description"`
}
json.NewDecoder(resp.Body).Decode(&e)
return nil, fmt.Errorf(
"token request failed: %s: %s %s", resp.Status, e.Error, e.Description,
)
}
var token Token
if err = json.NewDecoder(resp.Body).Decode(&token); err != nil {
return nil, err
}
return &token, nil
}Using it. openBrowser is a function of the app which opens a URL in the
default browser: xdg-open on Linux, rundll32 url.dll,FileProtocolHandler on
Windows, open on macOS, or what the UI framework of the app has for it.
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
defer cancel()
token, err := novaauth.Login(
ctx, "https://dev.nova.storage", "jevido-nova",
"filesystem_read filesystem_write account_read", openBrowser,
)
if err != nil {
return err
}
req, _ := http.NewRequest("GET", "https://dev.nova.storage/api/user", nil)
req.Header.Set("Authorization", "Bearer "+token.AccessToken)