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 /

The endpoint of HTTP API which provide the url to create a new token.

GET / HTTPS/1.1
Accept: application/json
HTTP/1.0 200 OK
Content-Type: application/json
Link: <https://example.com/tokens/>; rel=tokens

{
  "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 – when the server is available

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/ HTTPS/1.1
Accept: application/json
Content-Length: 0
HTTPS/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:
  • token_id (str) – the token id that holds the identity
  • alias (str) – the alias of the remote to access
Status Codes:
  • 200 – when successfully granted a temporary authorization
  • 404 – (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/ HTTPS/1.1
Accept: text/plain
HTTPS/1.1 200 OK
Content-Type: text/plain

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDAEMUvjBcX.../MuLLzC/m8Q==
Parameters:
  • token_id (str) – the token id that holds the identity
  • fingerprint (bytes) – the fingerprint of a public key to find
Status Codes:
  • 200 – when the public key is registered
  • 404 – (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/ HTTPS/1.1
Accept: application/json
HTTPS/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:
  • token_id (str) – the token id that holds the identity
  • fingerprint (bytes) – the fingerprint of a public key to delete
Status Codes:
  • 200 – when the public key is successfully deleted
  • 404 – (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 by create_access_token()
Status Codes:
  • 400 – when authentication is failed
  • 404 – when the given token_id doesn’t exist
  • 403 – when the token_id is already finalized
  • 200 – when authentication is successfully done
GET /tokens/(token_id: token_id)/masterkey/

Public part of the master key in OpenSSH authorized_keys (public key) format.

GET /tokens/0123456789abcdef/masterkey/ HTTPS/1.1
Accept: text/plain
HTTPS/1.1 200 OK
Content-Type: text/plain

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDAEMUvjBcX.../MuLLzC/m8Q==
Parameters:
  • token_id (str) – the token id that holds the identity
Status Codes:
  • 200 – when the master key is available
  • 500 – when the master key is unavailable
GET /tokens/(token_id: token_id)/remotes/

List all available remotes and their aliases.

GET /tokens/0123456789abcdef/remotes/ HTTPS/1.1
Accept: application/json
HTTPS/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 – when listing is successful, even if there are no remotes
GET /tokens/(token_id: token_id)/keys/

List registered keys to the token owner.

GET /tokens/0123456789abcdef/keys/ HTTPS/1.1
Accept: application/json
HTTPS/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 – when listing is successful, even if there are no keys
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/ HTTPS/1.1
Accept: application/json
Content-Type: text/plain

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDAEMUvjBcX.../MuLLzC/m8Q==
HTTPS/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 – when key registration is successful
  • 400 – (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-content-type) when the Content-Type is not text/plain
PUT /tokens/(token_id: token_id)/

Create a new access token.

PUT /tokens/0123456789abcdef/ HTTPS/1.1
Accept: application/json
Content-Length: 0
HTTPS/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 – when the access token is prepared
Response Headers:
 
  • Link – the link owner’s browser should redirect to
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/ HTTPS/1.1
Accept: application/json
HTTPS/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/tokens/0123456789abcdef/ma...>; 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/tokens/0123456789abcdef/mas..."
}
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 – 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.