A Simplified RESTful workflow

Logging in

All requests to the service require access tokens, so the first step in any RESTful workflow is to obtain an authentication token. You can acquire an access token by programatically logging in.

Procedure

1. Make a GET request to the /api/login endpoint that includes an Authorization header with your username and password in a MIME Base64 encoding;
2. Examine the response. The response code indicates whether the request succeeded, or how it failed;
3. A successful login request returns an authentication token that you can use in subsequent requests.

Example: Login request and response

A request to create a login session must supply the user's credentials in the following form:

user:password

• user is the user's login name
• password is the user's password

This example shows a login request and response for a user named exampleuser with password examplepassword.
Request:

curl -X POST https://trackhubregistry.org/api/login \
-d "username=exampleuser" \
-d "password=examplepassword"

200 OK
Content-type: application/json; charset=utf-8
...
{
  "auth_token": "52d07632507e6c17f4dca1a2c6b76fb146078c2e",
  "email": "user@email.com",
  "is_account_activated": true
}

The response code indicates whether the request succeeded, or how it failed.

• If the request is successful, the server returns HTTP response code 200 (OK). The response body is a JSON object with a single key (auth_token), whose value is the access token. This token must be included as an Authorization: Token header in all subsequent requests.
• If the credentials supplied in the authentication header are invalid, the server returns HTTP response code 401.

Example Clients

use strict;
use warnings;

use JSON;
use HTTP::Request::Common;
use LWP::UserAgent; # install LWP::Protocol::https as well

my $ua = LWP::UserAgent->new(ssl_opts => { verify_hostname => 0 });
my $payload = ['username' => 'exampleuser', 'password' => 'examplepass'];

my $request = POST('https://trackhubregistry.org/api/login', $payload);

my $response = $ua->request($request);
my $auth_token;
if ($response->is_success) {
  $auth_token = from_json($response->content)->{auth_token};
  print "Logged in [", $auth_token, "]\n" if $auth_token;
} else {
  die sprintf "Couldn't login, reason: %s [%d] ", $response->content, $response->code;
}