API: Authentication

This page details how to authenticate with the API server. Presently, every endpoint except /auth/signup and /auth/logout requires authentication. Any unauthenticated requests to any other endpoints will return a 401 error.

The API server uses token-based authentication. Any authenticated requests must be made with the Authorization header formatted as Token {actual_token}. For example:

Authorization: Token 675b51c53c94a5af46948097659984cd5a272507

Sign up

POST /auth/signup

Creates a new user on the API server based on the provided data encoded in application/x-www-form-urlencoded. If the user was created successfully, the server returns a token that will be valid for 24 hours.

POST /auth/signup HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 92
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:8000
User-Agent: HTTPie/0.9.2

username=admin&password1=hunter2&password2=hunter2&email=admin%40example.com&accept_tos=true

HTTP/1.0 200 OK
Content-Type: application/json
Date: Sat, 31 Oct 2015 19:07:35 GMT
Server: WSGIServer/0.1 Python/2.7.6
X-Frame-Options: SAMEORIGIN

{
    "errors": {}, 
    "success": true, 
    "token": "445f9c5bd2fa15d97f6aa3366d44e313df388cb2"
}

If some or all of the fields are missing then the server will return an non-empty errors object that describes the form error(s).

POST /auth/signup HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 14
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:8000
User-Agent: HTTPie/0.9.2

username=admin

HTTP/1.0 200 OK
Content-Type: application/json
Date: Sat, 31 Oct 2015 19:08:03 GMT
Server: WSGIServer/0.1 Python/2.7.6
X-Frame-Options: SAMEORIGIN

{
    "errors": {
        "accept_tos": [
            "This field is required."
        ], 
        "email": [
            "This field is required."
        ], 
        "password1": [
            "This field is required."
        ], 
        "password2": [
            "This field is required."
        ], 
        "username": [
            "A user with that username already exists."
        ]
    }, 
    "success": false, 
    "token": null
}

Log in

POST /auth/login

Authenticates a user on the API server based on the provided data encoded in application/x-www-form-urlencoded. If authentication was successful, the server returns a token that will be valid for 24 hours.

POST /auth/login HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 27
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:8000
User-Agent: HTTPie/0.9.2

username=admin&password=hunter2

HTTP/1.0 200 OK
Content-Type: application/json
Date: Sat, 31 Oct 2015 19:02:40 GMT
Server: WSGIServer/0.1 Python/2.7.6
X-Frame-Options: SAMEORIGIN

{
    "errors": {}, 
    "success": true, 
    "token": "1ad9bda28fd52c4f339102e3a97468a8f1b9ffce"
}

If some or all of the fields are missing then the server will return an non-empty errors object that describes the form error(s).

HTTP/1.0 200 OK
Content-Type: application/json
Date: Sat, 31 Oct 2015 19:02:37 GMT
Server: WSGIServer/0.1 Python/2.7.6
X-Frame-Options: SAMEORIGIN

{
    "errors": {
        "password": [
            "This field is required."
        ], 
        "username": [
            "This field is required."
        ]
    }, 
    "success": false, 
    "token": null
}

Log out

POST /auth/logout

Invalidates the user's current token on the server. Returns 200 if the provided token is valid and a JSON body that describes whether or not the operation was successful.

POST /auth/logout HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Token 675b51c53c94a5af46948097659984cd5a272507
Connection: keep-alive
Content-Length: 0
Host: localhost:8000
User-Agent: HTTPie/0.9.2

HTTP/1.0 200 OK
Allow: POST, OPTIONS
Content-Type: application/json
Date: Sat, 31 Oct 2015 18:45:35 GMT
Server: WSGIServer/0.1 Python/2.7.6
Vary: Accept
X-Frame-Options: SAMEORIGIN

{
    "success": true
}