HTTP API¶
Server version¶
The release policy of Geofront follows Semantic Versioning, and the HTTP API which this docs covers also does the same. You can treat what you could do on Geofront 1.2.3:
- might be broken on Geofront 2.0.0;
- shouldn’t be broken 1.3.0;
- must not be broken on Geofront 1.2.4.
Also broken things on Geofront 1.2.3 might be fixed on Geofront 1.2.4.
So how does the server tell its version through HTTP API? It provides two headers that are equivalent:
- Server
- Which is a standard compliant header. The form follows also the standard
e.g.
Geofront/1.2.3
. - X-Geofront-Version
- Which is a non-standard extended header. The form consists of only the
version number e.g.
1.2.3
.
These headers even are provided when the response is error:
HTTP/1.0 404 Not Found
Content-Length: 9
Content-Type: text/plain
Date: Tue, 01 Apr 2014 17:46:36 GMT
Server: Geofront/0.9.0
X-Geofront-Version: 0.9.0
Not Found
Endpoints¶
-
GET
/masterkey/
¶ Public part of the master key in OpenSSH authorized_keys (public key) format.
GET /masterkey/ HTTP/1.1 Accept: text/plain
HTTP/1.1 200 OK Content-Type: text/plain ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDAEMUvjBcX.../MuLLzC/m8Q==
Status Codes: - 200 OK – when the master key is available
- 500 Internal Server Error – when the master key is unavailable
-
GET
/
¶ The endpoint of HTTP API which provide the url to create a new token.
GET / HTTP/1.1 Accept: application/json
HTTP/1.0 200 OK Content-Type: application/json Link: <https://example.com/tokens/>; rel=tokens Link: <https://example.com/masterkey/>; rel=masterkey { "master_key_url": "https://example.com/masterkey/", "tokens_url": "https://example.com/tokens/" }
Response Headers: - Link – the url to create a new token. the equivalent to the response content
Status Codes: - 200 OK – when the server is available
New in version 0.4.0: Added
"master_key_url"
field in the result and Link header ofrel=masterkey
.New in version 0.2.0.
-
POST
/tokens/
(token_id: token_id)/remotes/
(alias)/
¶ Temporarily authorize the token owner to access a remote. A made authorization keeps alive in a minute, and then will be expired.
POST /tokens/0123456789abcdef/remotes/web-1/ HTTP/1.1 Accept: application/json Content-Length: 0
HTTP/1.1 200 OK Content-Type: application/json { "success": "authorized", "remote": {"user": "ubuntu", "host": "192.168.0.5", "port": 22}, "expires_at": "2014-04-14T14:57:49.822844+00:00" }
Parameters: Status Codes: - 200 OK – when successfully granted a temporary authorization
- 404 Not Found – (
not-found
) when there’s no such remote
-
GET
/tokens/
(token_id: token_id)/keys/
(fingerprint: fingerprint)/
¶ Find the public key by its
fingerprint
if it’s registered.GET /tokens/0123456789abcdef/keys/50:5a:9a:12:75:8b:b0:88:7d:7a:8d:66:29:63:d0:47/ HTTP/1.1 Accept: text/plain
HTTP/1.1 200 OK Content-Type: text/plain ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDAEMUvjBcX.../MuLLzC/m8Q==
Parameters: Status Codes: - 200 OK – when the public key is registered
- 404 Not Found – (
not-found
) when there’s no such public key
-
DELETE
/tokens/
(token_id: token_id)/keys/
(fingerprint: fingerprint)/
¶ Delete a public key.
DELETE /tokens/0123456789abcdef/keys/50:5a:9a:12:75:8b:b0:88:7d:7a:8d:66:29:63:d0:47/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json { "72:00:60:24:66:e8:2d:4d:2a:2a:a2:0e:7b:7f:fc:af": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCom2CDLekY...5CeYsvSdrTWA5 ", "78:8a:09:c8:c1:24:5c:89:76:92:b0:1e:93:95:5d:48": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEA16iSKKjFHOgj...kD62SYXNKY9c= ", "ab:3a:fb:30:44:e3:5e:1e:10:a0:c9:9a:86:f4:67:59": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAzzF8c07pzgKk...r+b6Q9VnWWQ== " }
Parameters: Status Codes: - 200 OK – when the public key is successfully deleted
- 404 Not Found – (
not-found
) when there’s no such public key
-
GET
/tokens/
(token_id: token_id)/authenticate/
¶ Finalize the authentication process. It will be shown on web browser.
Parameters: - token_id (
str
) – token id created bycreate_access_token()
Status Codes: - 400 Bad Request – when authentication is failed
- 404 Not Found – when the given
token_id
doesn’t exist - 403 Forbidden – when the
token_id
is already finalized - 200 OK – when authentication is successfully done
- token_id (
-
GET
/tokens/
(token_id: token_id)/masterkey/
¶ Public part of the master key in OpenSSH authorized_keys (public key) format.
GET /tokens/0123456789abcdef/masterkey/ HTTP/1.1 Accept: text/plain
HTTP/1.1 301 Moved Permanently Content-Type: text/plain ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDAEMUvjBcX.../MuLLzC/m8Q==
Parameters: - token_id (
str
) – the token id that holds the identity
Status Codes: - 200 OK – when the master key is available
- 500 Internal Server Error – when the master key is unavailable
Deprecated since version 4.0.0: Use
GET /masterkey/
instead.Changed in version 4.0.0: It now responds with 301 Moved Permanently instead of 200 OK. It redirects to
GET /masterkey/
which is the new master key url.- token_id (
-
GET
/tokens/
(token_id: token_id)/remotes/
¶ List all available remotes and their aliases.
GET /tokens/0123456789abcdef/remotes/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json { "web-1": {"user": "ubuntu", "host": "192.168.0.5", "port": 22}, "web-2": {"user": "ubuntu", "host": "192.168.0.6", "port": 22}, "web-3": {"user": "ubuntu", "host": "192.168.0.7", "port": 22}, "worker-1": {"user": "ubuntu", "host": "192.168.0.25", "port": 22}, "worker-2": {"user": "ubuntu", "host": "192.168.0.26", "port": 22}, "db-1": {"user": "ubuntu", "host": "192.168.0.50", "port": 22}, "db-2": {"user": "ubuntu", "host": "192.168.0.51", "port": 22} }
Parameters: - token_id (
str
) – the token id that holds the identity
Status Codes: - 200 OK – when listing is successful, even if there are no remotes
- token_id (
-
GET
/tokens/
(token_id: token_id)/keys/
¶ List registered keys to the token owner.
GET /tokens/0123456789abcdef/keys/ HTTP/1.1 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json { "50:5a:9a:12:75:8b:b0:88:7d:7a:8d:66:29:63:d0:47": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDAEMUvjBcX.../MuLLzC/m8Q== ", "72:00:60:24:66:e8:2d:4d:2a:2a:a2:0e:7b:7f:fc:af": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCom2CDLekY...5CeYsvSdrTWA5 ", "78:8a:09:c8:c1:24:5c:89:76:92:b0:1e:93:95:5d:48": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEA16iSKKjFHOgj...kD62SYXNKY9c= ", "ab:3a:fb:30:44:e3:5e:1e:10:a0:c9:9a:86:f4:67:59": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAzzF8c07pzgKk...r+b6Q9VnWWQ== " }
Parameters: - token_id (
str
) – the token id that holds the identity
Status Codes: - 200 OK – when listing is successful, even if there are no keys
- token_id (
-
POST
/tokens/
(token_id: token_id)/keys/
¶ Register a public key to the token. It takes an OpenSSH public key line through the request content body.
POST /tokens/0123456789abcdef/keys/ HTTP/1.1 Accept: application/json Content-Type: text/plain ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDAEMUvjBcX.../MuLLzC/m8Q==
HTTP/1.1 201 Created Content-Type: text/plain Location: /tokens/0123456789abcdef/keys/50:5a:9a:12:75:8b:b0:88:7d:7a:8d:66:29:63:d0:47 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDAEMUvjBcX.../MuLLzC/m8Q==
Parameters: - token_id (
str
) – the token id that holds the identity
Status Codes: - 201 Created – when key registration is successful
- 400 Bad Request – (
unsupported-key-type
) when the key type is unsupported, or (invalid-key
) the key format is invalid, or (deuplicate-key
) the key is already used - 415 Unsupported Media Type – (
unsupported-content-type
) when the Content-Type is not text/plain
- token_id (
-
PUT
/tokens/
(token_id: token_id)/
¶ Create a new access token.
PUT /tokens/0123456789abcdef/ HTTP/1.1 Accept: application/json Content-Length: 0
HTTP/1.1 202 Accepted Content-Type: application/json Date: Tue, 15 Apr 2014 03:44:43 GMT Expires: Tue, 15 Apr 2014 04:14:43 GMT Link: <https://example.com/login/page/?redirect_uri=...>; rel=next { "next_url": "https://example.com/login/page/?redirect_uri=..." }
Parameters: - token_id (
str
) – an arbitrary token id to create. it should be enough random to avoid duplication
Status Codes: - 202 Accepted – when the access token is prepared
Response Headers: - Link – the link owner’s browser should redirect to
- token_id (
-
GET
/tokens/
(token_id: token_id)/
¶ The owner identity that the given token holds if the token is authenticated. Otherwise it responds 403 Forbidden, 404 Not Found, 410 Gone, or 412 Precondition Failed. See also
get_identity()
.GET /tokens/0123456789abcdef/ HTTP/1.1 Accept: application/json
HTTP/1.0 200 OK Content-Type: application/json Link: <https://example.com/tokens/0123456789abcdef/remo...>; rel=remotes Link: <https://example.com/tokens/0123456789abcdef/keys/>; rel=keys Link: <https://example.com/masterkey/>; rel=masterkey { "identifier": "dahlia", "team_type": "geofront.backends.github.GitHubOrganization", "remotes_url": "https://example.com/tokens/0123456789abcdef/remotes/", "keys_url": "https://example.com/tokens/0123456789abcdef/keys/", "master_key_url": "https://example.com/masterkey/" }
Parameters: - token_id (
str
) – the token id that holds the identity
Response Headers: - Link – the url to list remotes (
rel=remotes
), public keys (rel=keys
), and master key (rel=masterkey
)
Status Codes: - 200 OK – when the token is authenticated
Changed in version 0.2.0: The response contains
"remotes_url"
,"keys_url"
, and"master_key_url"
, and equivalent three Link headers.- token_id (