Authentication

Authentication for API calls is performed by obtaining a JWT token in advance.

This token has a lifespan of 1 hour, which means you need to obtain a new token regularly. It is possible to refresh the token to extend its validity. The refresh token can be used for up to 12 hours after the initial authentication.

Obtaining a JWT token

You can obtain a new JWT token by making a POST request to the /api/v2/account/token/ endpoint.

Note

New in version 2.1: the email is case-insensitive.

Request:

POST /api/v2/account/token/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "email": "email@domain.com",
  "password": "xxxxxxxxxx",
}

Response:

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

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b",
  "access": "eyJhbGciOiJIUzIInR5cCI6I.48rgjeijw2qef24o3du2eufonefwe",
  "user": {
    "date_joined": "2017-11-22T10:04:13Z",
    "last_login": "2019-03-19T06:54:08Z",
    "user_uuid": "ut8rie3",
    "operator_name": "Stella",
    "language": "en",
    "fullname": "Stella User",
    "first_name": "Stella",
    "last_name": "User",
    "cell_phone_number": "0606060606",
    "email": "user.stella@kosc-telecom.fr",
    "groups": [
      11
    ],
    "operator_uuid": "9jxt7k2r"
  }
}

If the credentials are invalid, the API returns HTTP 401.

Using the JWT token

Warning

Initially, the token could be provided for each request via a query string parameter. This behavior is deprecated and will soon be disabled for security reasons. You are invited to migrate to HTTP header authentication.

Once obtained, the token must be provided for each request via the Authorization header Bearer <TOKEN>.

Request:

GET /api/users/ut8rie3/ HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzIInR5cCI6I.48rgjeijw2qef24o3du2eufonefwe
Host: extranet.kosc-telecom.fr

Response:

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

{
  "date_joined": "2017-11-22T10:04:13Z",
  "last_login": "2019-03-19T06:54:08Z",
  "user_uuid": "ut8rie3",
  "operator_name": "Stella",
  "language": "en",
  "fullname": "Stella User",
  "first_name": "Stella",
  "last_name": "User",
  "cell_phone_number": "0606060606",
  "email": "user.stella@kosc-telecom.fr",
  "groups": [
      11
  ],
  "operator_uuid": "9jxt7k2r"
}

When the token is expired, the API returns HTTP 403.

HTTP/1.1 403 FORBIDDEN
Content-Type: application/json

{
    "error": {
        "detail": "Given token not valid for any token type",
        "code": "token_not_valid",
        "messages": [
            {
                "token_class": "AccessToken",
                "token_type": "access",
                "message": "Token is invalid or expired"
            }
        ]
    },
    "apirequest_uuid": "KOSC_8f340d1e-4ccf-40c0-a1a4-7a13046aea4e"
}

Refreshing the JWT token

As long as the refresh token is not expired, you can refresh the access token by making a POST request to the /api/v2/account/token/refresh/ endpoint.

Note

Token refresh can be repeated (token 1 > token 2 > token 3). A token can be refreshed for up to 12 hours after the first one was obtained.

Request:

POST /api/v2/account/token/refresh/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "refresh": "eyJhbGciOiJIUzIInR5cCI6I.48rgjeijw2qef24o3du2eufonefwe"
}

Response:

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

{
    "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWN",
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBl"
}

Verifying the token

You can verify the validity of a token by making a POST request to the /api/v2/account/token/verify/ endpoint.

Request:

POST /api/v2/account/token/verify/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzIInR5cCI6I.48rgjeijw2qef24o3du2eufonefwe"
}

If the token is still valid, the API returns a 200 response:

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

If the token is no longer valid, the API returns a 401 response:

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