1. What is Securatta ?

Securatta is, at the moment, a naive authentication service based on JWT

2. Rest API

The Rest API has been documented using Restdocs, meaning is generated once all API tests have been passed. That ensures that the API documentation is accurate and up-to-date.

2.1. /api/v1/auth/token

This endpoint returns a token as exchange for valid credentials. The resulting token could be used to authenticate the user in subsequent calls.

2.1.1. 200

Request

The call should have the user’s valid credentials in order to receive a valid token along witht the basic user details.

curl
$ curl 'http://localhost:5050/api/v1/auth/token' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json; charset=UTF-8' -d '{
  "username" : "username",
  "password" : "password"
}'
http
POST /api/v1/auth/token HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: localhost:5050
Content-Length: 56

{
  "username" : "username",
  "password" : "password"
}
Response

If the credentials are correct then a 200 status code will be received along with basic user details including the token expiration timestamp.

response
HTTP/1.1 201 Created
content-type: application/json
content-encoding: gzip
transfer-encoding: chunked
Content-Length: 251

{
  "user" : {
    "name" : "john",
    "username" : "username"
  },
  "token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzZWN1cmF0dGEiLCJuYW1lIjoiam9obiIsInVzZXJuYW1lIjoidXNlcm5hbWUifQ.7J7CVZsfsAMGeH7Eh_sFl7CTAvDkMXbHd_An_LsAKXw",
  "expirationDate" : null
}

2.1.2. 401

Sometimes the request may not have valid credentials or may not have credentials at all.

Request

Passing an invalid username or password:

curl
$ curl 'http://localhost:5050/api/v1/auth/token' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json; charset=UTF-8' -d '{
  "username" : "unknown",
  "password" : "whatever"
}'
http
POST /api/v1/auth/token HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: localhost:5050
Content-Length: 55

{
  "username" : "unknown",
  "password" : "whatever"
}
Response

The response in this case returns a 401 status code and no body

response
HTTP/1.1 401 Unauthorized
content-type: text/plain;charset=UTF-8
content-encoding: gzip
transfer-encoding: chunked

2.2. /api/v1/auth/check

This enpoint is another way of authentication, but instead of using username and password, you can use a JWT token.

2.2.1. 200

Request

The request should have an Authorization header containing the keyword Bearer an space and then the token previously obtained from Securatta.

POST /api/v1/auth/check HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzZWN1cmF0dGEiLCJuYW1lIjoiam9obiIsInVzZXJuYW1lIjoidXNlcm5hbWUifQ.7J7CVZsfsAMGeH7Eh_sFl7CTAvDkMXbHd_An_LsAKXw
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: localhost:5050
Response

If the credentials are correct then a 200 status code will be received along with basic user details.

HTTP/1.1 200 OK
content-type: application/json
content-encoding: gzip
transfer-encoding: chunked
Content-Length: 251

{
  "user" : {
    "name" : "john",
    "username" : "username"
  },
  "token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzZWN1cmF0dGEiLCJuYW1lIjoiam9obiIsInVzZXJuYW1lIjoidXNlcm5hbWUifQ.7J7CVZsfsAMGeH7Eh_sFl7CTAvDkMXbHd_An_LsAKXw",
  "expirationDate" : null
}

2.2.2. 401

The authentication fails every time the user provides an invalid token or if the authorization token is not present at all.

Request

Providing an empty authorization header:

POST /api/v1/auth/check HTTP/1.1
Authorization:
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: localhost:5050
Response
HTTP/1.1 401 Unauthorized
content-type: text/plain;charset=UTF-8
content-encoding: gzip
transfer-encoding: chunked

3. Development