# Authentication

`POST` `/api/auth/register`

  register a user

  Example request:

      POST /api/auth/register HTTP/1.1
      Content-Type: application/json

  Example responses:

  - successful registration

      HTTP/1.1 201 CREATED
      Content-Type: application/json

      {
        "auth_token": "JSON Web Token",
        "message": "Successfully registered.",
        "status": "success"
      }

  - error on registration

      HTTP/1.1 400 BAD REQUEST
      Content-Type: application/json

      {
        "message": "Errors: Valid email must be provided.\n",
        "status": "error"
      }

  Request JSON Object

    - username (string) – user name (3 to 12 characters required)

    - email (string) – user email

    - password (string) – password (8 characters required)

    - password_conf (string) – password confirmation

  Status Codes

    - 201 Created – Successfully registered.

    - 400 Bad Request –

      - Invalid payload.

      - Sorry. That user already exists.

      - Errors:

          - 3 to 12 characters required for usernanme.

          - Valid email must be provided.

          - Password and password confirmation don’t match.

          - 8 characters required for password.

    - 403 Forbidden – Error. Registration is disabled.

    - 500 Internal Server Error – Error. Please try again or contact the administrator.

`POST` `/api/auth/login`

  user login

  Example request:

      POST /api/auth/login HTTP/1.1
      Content-Type: application/json

  Example responses:

  - successful login

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "auth_token": "JSON Web Token",
        "message": "Successfully logged in.",
        "status": "success"
      }

  - error on login

      HTTP/1.1 404 NOT FOUND
      Content-Type: application/json

      {
        "message": "Invalid credentials.",
        "status": "error"
      }

  Request JSON Object

    - email (string) – user email

    - password_conf (string) – password confirmation

  Status Codes

    - 200 OK – Successfully logged in.

    - 404 Not Found – Invalid credentials.

    - 500 Internal Server Error – Error. Please try again or contact the administrator.

`GET` `/api/auth/logout`

  user logout

  Example request:

      GET /api/auth/logout HTTP/1.1
      Content-Type: application/json

  Example responses:

  - successful logout

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "message": "Successfully logged out.",
        "status": "success"
      }

  - error on login

      HTTP/1.1 401 UNAUTHORIZED
      Content-Type: application/json

      {
        "message": "Provide a valid auth token.",
        "status": "error"
      }

  Request Headers

    - Authorization – OAuth 2.0 Bearer Token

  Status Codes

    - 200 OK – Successfully logged out.

    - 401 Unauthorized – Provide a valid auth token.

`GET` `/api/auth/profile`

  get authenticated user info

  Example request:

      GET /api/auth/profile HTTP/1.1
      Content-Type: application/json

  Example response:

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "data": {
          "admin": false,
          "bio": null,
          "birth_date": null,
          "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
          "email": "sam@example.com",
          "first_name": null,
          "language": "en",
          "last_name": null,
          "location": null,
          "nb_activities": 6,
          "nb_sports": 3,
          "picture": false,
          "sports_list": [
              1,
              4,
              6
          ],
          "timezone": "Europe/Paris",
          "total_distance": 67.895,
          "total_duration": "6:50:27",
          "username": "sam",
          "weekm": false
        },
        "status": "success"
      }

  Request Headers

    - Authorization – OAuth 2.0 Bearer Token

  Status Codes

    - 200 OK – success.

    - 401 Unauthorized –

      - Provide a valid auth token.

      - Signature expired. Please log in again.

      - Invalid token. Please log in again.

`POST` `/api/auth/profile/edit`

  edit authenticated user

  Example request:

      POST /api/auth/profile/edit HTTP/1.1
      Content-Type: application/json

  Example response:

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "data": {
          "admin": false,
          "bio": null,
          "birth_date": null,
          "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
          "email": "sam@example.com",
          "first_name": null,
          "language": "en",
          "last_name": null,
          "location": null,
          "nb_activities": 6,
          "nb_sports": 3,
          "picture": false,
          "sports_list": [
              1,
              4,
              6
          ],
          "timezone": "Europe/Paris",
          "total_distance": 67.895,
          "total_duration": "6:50:27",
          "username": "sam"
          "weekm": true,
        },
        "message": "User profile updated.",
        "status": "success"
      }

  Request JSON Object

    - first_name (string) – user first name

    - last_name (string) – user last name

    - location (string) – user location

    - bio (string) – user biography

    - birth_date (string) – user birth date (format: `%Y-%m-%d`)

    - password (string) – user password

    - password_conf (string) – user password confirmation

    - timezone (string) – user time zone

    - weekm (string) – does week start on Monday?

    - language (string) – language preferences

  Request Headers

    - Authorization – OAuth 2.0 Bearer Token

  Status Codes

    - 200 OK – User profile updated.

    - 400 Bad Request –

      - Invalid payload.

      - Password and password confirmation don’t match.

    - 401 Unauthorized –

      - Provide a valid auth token.

      - Signature expired. Please log in again.

      - Invalid token. Please log in again.

    - 500 Internal Server Error – Error. Please try again or contact the administrator.

`POST` `/api/auth/picture`

  update authenticated user picture

  Example request:

      POST /api/auth/picture HTTP/1.1
      Content-Type: multipart/form-data

  Example response:

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "message": "User picture updated.",
        "status": "success"
      }

  Form Parameters

    - file – image file (allowed extensions: .jpg, .png, .gif)

  Request Headers

    - Authorization – OAuth 2.0 Bearer Token

  Status Codes

    - 200 OK – User picture updated.

    - 400 Bad Request –

      - Invalid payload.

      - No file part.

      - No selected file.

      - File extension not allowed.

    - 401 Unauthorized –

      - Provide a valid auth token.

      - Signature expired. Please log in again.

      - Invalid token. Please log in again.

    - 413 Request Entity Too Large – Error during picture update: file size exceeds 1.0MB.

    - 500 Internal Server Error – Error during picture update.

`DELETE` `/api/auth/picture`

  delete authenticated user picture

  Example request:

      DELETE /api/auth/picture HTTP/1.1
      Content-Type: application/json

  Example response:

      HTTP/1.1 204 NO CONTENT
      Content-Type: application/json

  Request Headers

    - Authorization – OAuth 2.0 Bearer Token

  Status Codes

    - 204 No Content – picture deleted

    - 401 Unauthorized –

      - Provide a valid auth token.

      - Signature expired. Please log in again.

      - Invalid token. Please log in again.

    - 500 Internal Server Error – Error during picture deletion.

`POST` `/api/auth/password/reset-request`

  handle password reset request

  Example request:

      POST /api/auth/password/reset-request HTTP/1.1
      Content-Type: application/json

  Example response:

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "message": "Password reset request processed.",
        "status": "success"
      }

  Request JSON Object

    - email (string) – user email

  Status Codes

    - 200 OK – Password reset request processed.

    - 400 Bad Request – Invalid payload.

`POST` `/api/auth/password/update`

  update user password

  Example request:

      POST /api/auth/password/update HTTP/1.1
      Content-Type: application/json

  Example response:

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "message": "Password updated.",
        "status": "success"
      }

  Request JSON Object

    - password (string) – password (8 characters required)

    - password_conf (string) – password confirmation

    - token (string) – password reset token

  Status Codes

    - 200 OK – Password updated.

    - 400 Bad Request – Invalid payload.

    - 401 Unauthorized – Invalid token.

    - 500 Internal Server Error – Error. Please try again or contact the administrator.